---
title: Diagnose setup failures
description: Diagnose setup failures.
canonical_url: https://orchestor.io/docs/en/cli/workflows/setup-troubleshooting
markdown_url: https://orchestor.io/docs/en/cli/workflows/setup-troubleshooting.md
contentType: how-to
---

# 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](https://orchestor.io/signup). |
| Sign-in | `orc auth status --json` | Check the [active credential source](https://orchestor.io/docs/cli/quickstart.md). |
| Workspace creation | Returned ID and `workspaces get` | [Read back the same workspace](https://orchestor.io/docs/cli/workflows/new-workspace.md). |
| 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](https://orchestor.io/docs/cli/workflows/onboarding.md). |
| 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](https://orchestor.io/docs/cli/workflows/onboarding.md).

```bash
node --version
orc --version
orc --help
orc status --json
orc auth status --json
orc workspace current --json
orc setup skills --agent codex --status
```

If `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.

[Workflow index](https://orchestor.io/docs/cli/workflows.md) · [Setup reference](https://orchestor.io/docs/cli/setup.md)

If a failure remains, [report it and verify the fix](https://orchestor.io/docs/cli/workflows/workflow-feedback.md), including this workflow and the failed step.

---

[Documentation index](https://orchestor.io/docs/llms.txt)