Troubleshooting

Build errors

Build failures stop the pipeline before your connector can be deployed. Check the build logs in the Dev Portal under Monitoring → States.

Docker build failed

Error: Build docker image failed, with exit code <code>

The Dockerfile couldn't be processed. Common causes:

Dockerfile syntax error or referencing files that don't exist

Missing build dependencies

Base image not available

ENTRYPOINT used instead of CMD — only CMD is supported

Fix: Check your Dockerfile locally with docker build . to reproduce the error. Ensure all COPY paths exist and the base image is accessible.

Git clone failed

Error: Git clone failed with exit code <code>

The Dev Portal couldn't pull your code. Common causes:

Repository URL is wrong or unreachable

Branch doesn't exist

Credentials expired (token or deploy key)

Repository is private but no credentials configured

Fix: Go to VCS config and run Test connection to verify. For basic auth, check that the token hasn't expired. For deploy keys, confirm the public key is added to the repository.

Health check failed

Error: Checking image health took too long or Image health check exited with code <exitCode>

The health check runs your command with the health check arguments inside the built container. It must complete within 5 seconds and exit with code 0.

Common causes:

The command doesn't exist in the container (e.g. typo in command or arguments)

The command takes longer than 5 seconds to start

Missing runtime dependencies inside the image

Wrong command namespace (e.g. container:run:import instead of connector:run:import)

Fix: Run the health check locally:

docker run --rm your-image php ./bin/console connector:run:import --help

If it doesn't return within 5 seconds or exits with a non-zero code, that's your issue.

VCS secret missing

Error: "VCS secret from Vault is missing"

The credentials for your Git repository aren't stored. This happens when you switch authorization types without saving new credentials.

Fix: Go to VCS config, re-enter your credentials, and save.

Runtime errors

These errors occur while your connector is running and interacting with the Container API. Check the Logs and stdout/stderr in the Dev Portal.

400 Bad Request — Invalid output data

Endpoints: Write to output file, Stream to output

Trigger: Writing malformed data to the output or feedback file.

{
  "message": "Validation failed",
  "errors": { "data": "This value should be an array of items." }
}

Fix: Ensure you're sending an array of associative arrays in the data field:

// Correct
$this->containerApi->appendManyToOutputFile([
    ['id' => '1', 'name' => 'Product A'],
]);

// Wrong — not wrapped in an array
$this->containerApi->appendManyToOutputFile(
    ['id' => '1', 'name' => 'Product A']
);

400 Bad Request — Invalid batch size

Endpoints: Read input file (batch), Stream from input

Trigger: Reading input with a batch size outside the valid range.

Fix: Batch size must be between 1 and 999:

// Correct
$this->containerApi->yieldBatchFromInputFile(100);

// Wrong — 0 and 1000+ are invalid
$this->containerApi->yieldBatchFromInputFile(0);
$this->containerApi->yieldBatchFromInputFile(1000);

404 Not Found — Requested file not provided

Endpoints: Read input file, Read input file (batch), Stream from input

Trigger: Requesting an input file type that doesn't exist for your connector type.

Fix: Make sure you're using the right methods for your connector type:

Connector type	Valid input methods
Export	`yieldFromInputFile()`, `yieldBatchFromInputFile()`
Export delta	`yieldFromNewFile()`, `yieldFromModifiedFile()`, `yieldFromUnchangedFile()`, `yieldFromDeletedFile()`
Data source	No input — data source connectors write output, they don't read input

An export connector calling yieldFromNewFile() or a data source connector calling yieldFromInputFile() will get a 404.

409 Conflict — File size limit exceeded

Endpoints: Write to output file, Stream to output, Run storage upload

Trigger: The total output file size has reached the maximum allowed limit.

Fix: Break large datasets into smaller chunks. The PHP SDK automatically chunks writes at 200,000 attributes per request, but the total file size is still limited. If you're hitting this limit, consider:

Writing fewer columns per product

Splitting the import across multiple runs

Contacting support to raise the limit

429 Too Many Requests — Rate limit exceeded

Endpoints: Add log, Add notification

Trigger: Too many log or notification calls in a short window. The limits are 300 log lines per minute and 7,200 per connector run.

Fix:

Don't log inside tight loops — log summaries instead

Use info() for important messages, not for every product

Batch diagnostic information into fewer messages

Use stdout for verbose debugging during development

500 Internal Server Error — Invalid file

Endpoints: Read input file, Read input file (batch)

Trigger: The input file is corrupted or in an unexpected format.

Fix: This is usually a platform-side issue. Check that the site has valid data and try re-running. If it persists, check the Container API failure logs for details.

Sync errors

Connector version not built

Error: "This version is not built yet"

Trigger: Trying to sync a connector that hasn't been built successfully.

Fix: Trigger a build first. Check the build status in the Release configuration page.

Sync forbidden

Error: "Sync to dev is forbidden"

Trigger: The connector version is not in the correct state for syncing, or required configuration is missing.

Fix: Ensure all required configuration steps are complete (VCS config, application config, and type-specific config). The sidebar in the Dev Portal shows which steps are complete with green checkmarks.

PHP SDK exceptions

The SDK throws typed exceptions you can catch in your code:

Exception	When
`ApiFailureException`	Any Container API call fails
`FileNotFoundException`	Input file not available (404)
`BadRequestException`	Invalid request data (400)
`NoMoreResultException`	End of input reached when iterating
`LogFailed`	Logging call failed
`NotificationFailed`	Notification call failed
`StoreFileFailed`	Storage write failed
`UploadToTransportFailed`	Transport server upload failed

All SDK exceptions implement ContainerApiException, so you can catch that as a base type for generic error handling.

Troubleshooting

On this page