Diagnose setup failures
Identify the failing stage: installation, authentication, target selection, permissions, or agent connection.
Steps
For initial setup, identify the failing stage before repeating the workflow:
| Stage | Evidence | Next action |
|---|---|---|
| Signup and invitation | Email verification and invitation acceptance | Finish the remaining registration steps. |
| Sign-in | orc auth status --json | Check the active credential source. |
| Workspace creation | Returned ID and workspaces get | Read back the same workspace. |
| Candidate generation | orc observations get --workspace WORKSPACE_ID --json | Resolve the error and resume generation for the same target. |
| Confirmation | Returned initial_batch_id | Review and confirm candidates. |
| First observation | The same batch's state and results | Check runs batches get and runs batches results get. |
| Web Welcome completion | completed_at from workspaces setup get | Distinguish it from observation completion and finish remaining Web steps. |
For measurement_quota_exhausted, share the workspace ID and error with your contact. If init --website is an unknown option, use the stepwise commands for 0.5.0.
node --version
orc --version
orc --help
orc status --json
orc auth status --json
orc workspace current --json
orc setup skills --agent codex --statusIf orc is missing, check Node.js and the install directory on PATH. For 401, inspect the active credential source; for 403, inspect the target and required permission; for an empty list, inspect the workspace and available data. Read individual status fields rather than treating exit code 0 as a health result. Inspect Skills states: installed, missing, broken, version-drift, and conflict. Do not delete ordinary files reported as conflicts. Diagnose MCP registration, OAuth, and the actual read separately. Share the version, redacted error, target ID, and reproduction steps.
If a failure remains, report it and verify the fix, including this workflow and the failed step.