Skip to main content

Troubleshooting

View as Markdown

Troubleshooting

Common issues when building and running pipelines, and how to fix them.

How errors are classified​

Errors fall into two categories depending on when they occur:

  • Startup errors (init-time) happen while the engine validates and initialises the pipeline, before any data flows: invalid configuration (a required field missing, a value out of range, a referenced profile that does not exist), a missing Python dependency, a failed validation call (nodes like llm_openai make a test API call on startup to verify the key and model), or a lane mismatch. The engine reports the error immediately and the pipeline does not run — no data is processed.
  • Runtime errors happen during execution: an LLM API error (rate limit, context overflow, outage), a vector store timeout, a malformed document that cannot be chunked, or an agent exceeding its iteration cap. A runtime error stops the current pipeline run; nodes that already streamed output are not rolled back, and concurrent runs on the same pipeline are unaffected.

Either way the engine emits a structured error event over the WebSocket protocol with the node ID, message and type, and a stack trace for Python-level errors. The CLI prints these as they arrive; SDK clients receive them on the event stream. The full schema is in WebSocket Events, and recovery patterns (retries, fallbacks, guardrails) live in Error Handling.

Can't connect to the engine​

  • Connection refused / timeout. Nothing is listening on the URI. Start a local engine (the VS Code extension or a self-hosted container on port 5565), or point ROCKETRIDE_URI at your Cloud endpoint.
  • Unauthorized against Cloud. Set ROCKETRIDE_APIKEY to a valid API token (ROCKETRIDE_AUTH is read only by the MCP servers, not the SDKs or CLI).
  • Silent insecure downgrade. Against Cloud, an http:///ws:// (or bare host:port) URI drops to an unencrypted connection. Use https:// or wss://, see the WebSocket protocol.

Pipeline starts but no output comes back​

  • Wrong source for the job. A chat source expects chat(); a webhook / file source expects send() / pipe() (or upload). Driving a chat pipeline with send() (or vice versa) produces nothing. Match the method to the source node.
  • Pipeline isn't actually running. Uploads against a stale or terminated task token return nothing. Start the pipeline, then feed it.

The response is empty or under the wrong key​

  • Response key mismatch. A response node with a custom laneName puts the result under that name, not the default. Read the key your pipeline actually emits (the result's result_types tells you which key carries which lane), or use the default response config.

"Lane not supported" / "Lane mismatch" errors​

The output lane of one node must match the input lane of the next. Check both ends against the Nodes and fix the mismatched input connection.

Agent pipeline fails to start​

  • Missing control connections. Agents need their helpers wired via control on the helper, not the agent. agent_rocketride requires exactly one LLM and one memory; agent_crewai / agent_langchain take no memory. See Agents & tools.

Resources leak / connections pile up​

Always close the client when done (use the SDK's context manager / terminate()), and start a long-lived pipeline once rather than per request.

Last updated on