Troubleshooting

Runtime is not ready

Run:

pnpm exec orchard doctor --json

doctor is read-only. It reports whether tooling (Node/pnpm, optional harness CLIs) and repo config are ready. There is no database, schema, or queue to check: orchard run executes workflows in-process with createLocalRuntime() and has nothing external to provision.

Generated artifact preview reports source drift

orchard preview refuses to return stale manifest metadata when a saved source file no longer matches its recorded sourceHash. Regenerate the workflow with orchard generate, or preview by explicit path if you intentionally use a custom workflow directory.

orchard run hangs on an approval gate

orchard run can only prompt for an approval decision when it is attached to an interactive terminal (stdin and stderr are TTYs). Run it interactively so it can host the gate itself; see Use approval gates.

A non-interactive invocation (piped stdin, CI) cannot resolve a pending gate: there is no external process or command that can reach into a running orchard run's in-process event bus, so the run stays parked until you stop it. Avoid approval-gated workflows for non-interactive orchard run calls, or pass --skip-approval to orchard generate when that gate is the built-in generation approval step.

Harness auth failures

Fix harness configuration outside the workflow retry loop:

• Cursor: install the Cursor CLI and run cursor-agent login, or pass a CURSOR_API_KEY through cursor({ apiKey }).
• Codex: install/configure @openai/codex-sdk and the OpenAI credentials/model expected by your workflow.
• Claude: install Claude Code and run claude auth login, or pass an Anthropic API key through claude({ apiKey }).

Orchard wraps these unrecoverable setup failures in NonRetryableHarnessError so the in-process runtime does not spend its retry attempts on unchanged credentials or missing binaries.