Troubleshooting

Exit codes

Client commands exit with one stable code per failure class. Branch on the code, not the message.

Code	Name	Class	Meaning
0	OK	success	Command completed
1	CRASH	unknown	Unexpected error — a bug, a filesystem problem, or an unclassified failure
2	ACT_GATE_REFUSED	policy refusal	The act gate, authority or entitlement refused the act (also: lease tool policy none, unknown executor, privileged act not executed/approved)
3	AUTH_REQUIRED	policy refusal	Credential missing, expired, or not empowered (HTTP 401/403)
4	RESOURCE_CONFLICT	user error	Resource exists or state conflict (HTTP 409); also a cloud-sync conflict
5	NOT_FOUND	user error	Resource not found (HTTP 404)
6	OPERATION_TIMEOUT	service failure	The server did not answer in time; vagaris runctl attach past its --timeout
7	PROTOCOL_MISMATCH	user error	CLI/server protocol versions differ — run vagaris update
8	LEASE_INVALID	policy refusal	Lease expired, revoked, or bound to another node
9	NODE_REVOKED	policy refusal	This machine's enrolment has been revoked
10	SPAWN_CEILING_FULL	policy refusal	Too many concurrent runs
11	SERVICE_UNAVAILABLE	service failure	Server unreachable, 5xx, or rate-limited
12	DEFERRED_TO_OPERATOR	deferred	Accepted, but awaits an operator or approval decision
13	USAGE_ERROR	user error	Bad arguments, malformed input, missing context

The five classes are what a script needs to tell apart: user error (fix the input and retry), policy refusal (ask for authority; retrying will not help), service failure (retry later), deferred (wait for a decision), unknown (report it).

vagaris dev uses the same scheme and additionally propagates the governance chain's own exit code when it exits. vagaris cloud push exits 2 on a conflict and 3 on a schema mismatch.

The error envelope

With --json, a failing client command prints one object instead of prose:

{
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "name": "auth",
    "exitCode": 3,
    "class": "policy_refusal",
    "reason": "Board access required"
  }
}

code is the slug from the table; reason is the human sentence (the server's own reason when there was one). Without --json the same failure prints the reason on stderr (prefixed API error <status>: when it came from the server) followed by a dim [CODE · class · exit N] line.

Common failures

Company ID is required. — pass --company-id, set VAGARIS_COMPANY_ID, or save it with vagaris context set --company-id <id>.

Exit 3 in a script, a browser opens interactively. — the instance is authenticated and the CLI has no credential for its API base. Interactively it starts the login flow; in a script set VAGARIS_API_KEY (an agent key from vagaris agent local-cli) or log in once on a terminal so the credential is in the keychain. See Login.

Fleet identity sign-in succeeded, but the OS credential store is unavailable; this login is not persisted. — no Keychain/Secret Service. The current command proceeds; each later command will prompt again. Install secret-tool (libsecret) on Linux, or use an API key.

Exit 7 PROTOCOL_MISMATCH. — the server is newer than the CLI. vagaris update, or vagaris update --to <version> to match a pinned server.

No config found and terminal is non-interactive. — vagaris run cannot onboard without a terminal. Run vagaris onboard --yes first.

Doctor found blocking issues. Not starting server. — run vagaris doctor --repair and read the repair hints; each names the command that fixes it. Common ones: the embedded PostgreSQL port 54329 or the server port 3100 already in use, a missing log directory, a missing secrets key file.

Unsupported bind preset for onboard — --bind accepts loopback, lan or tailnet only.

no CLI-hosted executor for adapter '<type>' (exit 2) — only claude-local and codex-local can be hosted by vagaris dev. See Executors.

lease A3 axis denies all tools (exit 2) — the lease carries no tool allowlist. That is the default; the seat's policy on the server must grant tools. See Permissions.

leaseVerified: false in the dev report — the server refused the lease on verification: expired, revoked, or bound to another node (--node-id). Claim again; check vagaris node status.

runctl cancel says the run is still running. — the kill-switch integrity gate did not confirm the process died, so the run is reported truthfully. Retry; if it persists the process on the host needs attention.

Enrolment timed out or was cancelled. — the approval URL printed by vagaris node enroll was not approved within two minutes. Run it again and approve promptly.

Warning: 'vagris' is deprecated; use 'vagaris' instead. — you invoked the legacy alias. Harmless; it only writes to stderr.

Garbled or missing terminal output. — vagaris tui-demo renders a hello-world screen to confirm the ANSI renderer works in your terminal (--no-animation for a static render).

Skills not linked into ~/.claude/skills. — agent local-cli only writes there with --install-skills plus consent (--yes non-interactively). See Coding-Agent Integration.

Wrong instance or config picked up. — the CLI walks up from the current directory looking for .vagris/config.json (or a legacy .paperclip/config.json) before falling back to the home directory. Run vagaris onboard with --config to see which file it resolved, or pass --data-dir to isolate. See Configuration.

Still stuck

Collect a bundle and open a request — Support.