Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Troubleshoot Pipelines

Fix common issues you may encounter when running or validating pipelines.

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.

PipelineTransformError​

Your pipeline couldn't be loaded or turned into deployable YAML. It's usually one of these issues:

  • The file doesn't import cleanly. It loads in your project's interpreter, so any import error, missing dependency, or missing secret surfaces here. A project .env is loaded first for exactly this reason, but only variables that aren't already set.
  • No .venv or venv was found above the pipeline file, so the CLI fell back to its own interpreter, which doesn't have Haystack. Pass --python with the interpreter that does, or install the deploy extra. For help, see Install the SDK.
  • The file defines more than one pipeline. Pick one with --entrypoint.
  • The wrong interpreter was auto-detected. Point at the right one with --python.

PipelineValidationError​

The platform found blocking (ERROR) issues in the generated YAML. The message lists them. Run haystack-enterprise validate pipeline.py to iterate quickly without deploying.

A common cause is a component that exists in one Haystack version but not another. Validation runs against the haystack-ai version your pipeline pins. If the platform declines that version, you get a warning saying the pin went unhonored, which means version-specific problems may have been missed.

"You need to connect at least one of the inputs (query or messages)"​

The platform won't serve a pipeline it can't route a query into. Either rename your sockets to conventional names (query, answers, replies, documents), which the SDK maps by inference, or pin the mapping in a <pipeline>.io.yaml. For help, see The io-config File.

PipelineRunError​

The sandbox run failed because of bad configuration, bad inputs, or a server error. The message carries what the platform returned.

run isn't pinned to your pipeline's haystack-ai version; the sandbox uses the platform's own Haystack. So a version-specific failure can appear in run but not in a deployed service, or the reverse. Use validate for the version-accurate check.

Transient failures (network errors, timeouts, 429, 5xx) are retried twice by default. Configuration and input errors always fail right away. --retries 0 disables retrying.