Troubleshooting

Start with correlation

Every server response includes x-request-id. Search structured server logs for that value. Set LOG_LEVEL=debug temporarily for node transitions, channel routing, and dependency diagnosis; return to info after investigation.

Startup fails

• A workflow directory with flow.yaml but no valid manifest prevents discovery.
• Manifest IDs must match directory names; referenced paths stay inside the root.
• Composable workflow names must be unique and dependencies acyclic.
• Every present source configuration file must use version: 1 and contain its required top-level collection. Missing files contribute no records; empty collections are valid.
• Configured provider and memory types require matching workspace drivers. Configured models require a general role and must reference a named provider.
• A non-empty drivers/ dependency setup requires both drivers/package.json and drivers/package-lock.json; inspect npm ci output when dependency installation fails.
• Integrated channel startup requires a valid encryption key, a sufficiently long shared secret, and loadable driver manifests.

With WORKSPACE_DISCOVERY_MODE=degraded, invalid workflow or driver packages are skipped and /ready returns 503 with sanitized issue summaries. Configuration schema and registry errors still fail application creation.

Run remains queued or suspended

Check ASYNC_RUN_CONCURRENCY, server health, and queue logs. When concurrency slots are full, accepted runs remain queued until a running run reaches a terminal state. A suspended run is waiting for interaction input; inspect /api/interaction-requests and the application event stream. A debug run in paused state needs the continue endpoint described in Debug runs.

Callback fails

Confirm HTTPS, allowlist matching, public DNS resolution, the shared HMAC secret, and receiver signature verification over the exact raw body. Poll the run to see attempts, next retry, and last error.

Remote runner fails

Compare the configured bearer tokens and fetch /v1/capabilities from the server network. Ensure the runner can reach model, HTTP, and MCP dependencies described in the execution request. Runner errors after acceptance are terminal remote attempt errors, not safe automatic fallback signals.

Channel is degraded

Inspect the instance's diagnostics and presentation blocks, then server logs. Verify CHANNEL_SECRET_KEY, driver discovery paths, and the channel instance configuration. For WhatsApp, pairing state can expire and upstream protocol changes can require a driver update.