Troubleshoot Deployments
What to do when a rollout fails, a service is missing, or an io-config key behaves unexpectedly.
Add --verbose (or -v) before the command name to see the SDK's INFO and DEBUG logs. It's a global option, so it must come before the command, not after.
ServiceNotFoundError
The named service doesn't exist and you passed --no-create. Check the name with haystack-enterprise service-status <name>, or drop --no-create to have it created.
DeploymentFailedError
The rollout reached DEPLOYMENT_FAILED. The API doesn't expose a failure reason, so the error points you at the service in Haystack Enterprise Platform, where the deployment logs are.
The usual cause is a dependency that installs locally but not in the deployed revision. Check the dependencies: pin in your io-config. It replaces the automatic haystack-ai pin rather than adding to it, so if you set it you must include haystack-ai yourself.
If you interrupted the command with Ctrl-C, the rollout continued on the platform. Check with service-status.
Deploy Exits with Code 1 After a Rollout Timeout
The deploy command waits up to 10 minutes for a rollout to finish. If the rollout doesn't finish in that time, the command exits with code 1 and prints that the new revision isn't confirmed to be serving, so a CI job fails instead of passing without the new revision live. The rollout itself continues on the platform, and the service may still come up.
To find out what happened, run haystack-enterprise service-status <name>. If the service reaches DEPLOYED or IDLE, the revision is serving, and you can re-run the job. If the status shows a failure, see DeploymentFailedError above. Slow rollouts of large managed services are a common cause of timeouts. If you don't want the job to wait for the rollout, pass --skip-activation to push the revision and activate it later.
The command exits with code 0 when you detach on purpose, either by pressing Ctrl-C or by passing --skip-activation.
FailedToCreateSharedPrototypeError
The share link couldn't be created. --share needs a deployed, active service, so you can't combine it with --skip-activation.
If the link is created but the CLI warns the chat UI may not render output well, the platform didn't classify your pipeline as a chat pipeline. Set pipeline_output_type: chat in the io-config.
An io-config Key Was Ignored
Unrecognized top-level keys are passed through to the pipeline config unchanged, with a note. This is intentional, so you can set a platform key newer than your installed SDK. It also means a typo like session_storge: true passes through silently, and the note is the only signal, so read it carefully.
Related Information
Was this page helpful?