Troubleshooting
Start with the observable state, preserve the execution record, and change one condition at a time. These paths cover the failures most likely to block a first production run.
Run is waiting
Check the instance state and pending approvals. A human_review block waits for a signal by design; a delayed block shows its next_run_at time. Send the required signal or approve it—do not restart the engine.
Open the focused guideExternal worker is not picking up work
Confirm the worker registered the exact handler name and tenant, can reach /api/v1/workers/poll, and is sending heartbeats. A name mismatch leaves work queued.
Open the focused guideConnection or port fails
Check ORCH8_HTTP_ADDR, container port publishing, and GET /health. Local defaults use port 8080; Cloud and reverse proxies may expose a different public origin.
Open the focused guide401 or 403
Send x-api-key and, for tenant resources, x-tenant-id. Confirm the key is not revoked and has the required capability. Never use --insecure-auth outside isolated local development.
Open the focused guideDatabase migration fails
Back up the database, run the version-matched migration command once, and inspect migration history before retrying. Do not skip versions or edit an applied migration.
Open the focused guideCredential does not resolve
Engine credentials use credentials:// IDs; Cloud Vault values use {{vault.name}}. Verify the credential belongs to the same tenant and that the worker receives only the resolved field it needs.
Open the focused guideCrash occurred during an external call
A saved output is safe to skip. An unknown outcome is not automatically safe to retry: reconcile with the provider using an idempotency key, then retry or complete the step deliberately.
Open the focused guideCollect a support bundle
Record the Orch8 version, UTC timestamp, instance ID, sequence version, current state, and sanitized logs. Remove API keys and resolved credential values. Include the output of orch8 doctor when available.