Troubleshooting

The hint system

When a command fails against a known API error, the CLI prints the base error followed by an actionable hint: line on stderr:

$ adj clone prod-pg16
Error: instance quota exceeded: per-user cap 3 reached (HTTP 429)
hint: you've hit your instance quota — destroy one ('adj destroy <id>') or ask an admin

The base error always has the shape <message> (HTTP <status>). Not every status has a specific hint — anything without one just prints the base error. -v / --verbose logs the underlying HTTP requests to stderr if you need more than the hint to diagnose something.

Common errors

Status	What it means	Hint / what to do
401	Your access token expired.	Usually invisible — the CLI auto-refreshes and retries once. If the refresh token is also expired, revoked, or reused, you get `session expired — run 'adj login'` and local tokens are cleared automatically. Just log in again.
403	You don't own the resource, or the action needs admin.	`only the instance owner can do this`. Admin-only commands (cluster provisioning, catalog share/delete, users, quota set, pools) return this for a developer account.
404	Not found, or an instance's credentials aren't ready yet.	`not found, or credentials are not available yet — check 'adj get <id>'`. Common right after `adj clone` returns without `--wait` — the instance exists but isn't `Ready` yet.
409 (no cluster)	The org has no registered cluster yet.	Ask an admin to run `adj cluster register`.
409 (active instances)	You tried `adj cluster rm` on a cluster that still has instances.	Destroy the cluster's instances first, or use `adj cluster deprovision` if you mean to tear down everything.
409 (child instances)	You tried `adj catalog delete` on a golden with running clones.	`destroy the child instances first, or re-run with --force to cascade them`.
409 (still referenced)	You tried `adj catalog delete --force` on a golden a pool or import record still references.	`a clone pool still references this golden — remove it first ('adj pool rm <pool>'); goldens created by an import keep their import record and cannot be catalog-deleted`.
429	You (or the org) hit the instance quota.	`you've hit your instance quota — destroy one ('adj destroy <id>') or ask an admin`. See Users and quotas.
503	The data-plane agent for your cluster is offline.	`the data-plane agent is offline — check cluster health ('adj cluster ls') and retry`.
504	The request timed out brokering through the agent.	`the request timed out brokering through the agent — retry in a moment`. Usually transient; the underlying action may still complete — check with `adj get <id>` before retrying a mutating command.

Deprovisioning older clusters

Deprovision can't find OpenTofu state for an older cluster — clusters provisioned by adj ≤ v0.1.0 (or with --module-dir) keep their state in that module checkout directory, not under ~/.config/adj. Re-run with --module-dir pointing at the original checkout.

Where to look

adj cluster ls / adj cluster status <name> — agent connectivity and last heartbeat. A disconnected or stale agent explains most 503/504s and slow clones.
adj org audit --verify — the org's hash-chained history. Useful for reconstructing "who did what, when" after something unexpected happened, and for confirming the audit trail itself hasn't been tampered with.
adj org usage — one-shot rollup of quota, users, goldens, clusters, pools, and imports; often faster than chasing the same facts across five separate commands.
adj get <id> — the source of truth for a single instance's current phase. Reach for it any time a command that touches an instance behaves unexpectedly (credentials not ready, still provisioning, etc.).
-v / --verbose on any command — logs the raw HTTP requests to stderr, useful when reporting an issue.

Login/session issues

If commands start failing with not logged in — run 'adj login' or session expired — run 'adj login' unexpectedly, someone (possibly you, from another machine) may have changed your password or run adj logout --all — both revoke every other session. See Account and sessions.

Still stuck

Check Cluster operations and Goldens and imports for the deeper mechanics behind the commands above, or the generated CLI reference for every flag on every command.