CLI errors
In plain output, a failure starts with error[CODE]. With --json, the response
includes code, reason, and next. A null next action means Volli cannot
recommend a safe retry from what it knows.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
Success |
1 |
The command ran and failed |
2 |
Invalid command, argument, or flag |
3 |
The app could not be reached |
For exit code 3, open Volli and check the connection with volli identify.
If a write fails and the response cannot confirm whether it landed, inspect the
current state before you retry.
Refusal codes
Section titled “Refusal codes”These entries come from the same recovery data as volli help exit-codes.
USAGE
The typed arguments do not match this verb's declared syntax.
Safe next action: Run `volli help <command>` and retry with the documented arguments.
INVALID_REQUEST
The request reached its verb but one value or value combination is invalid.
Safe next action: Read `volli help <command>`, correct the named value, and retry.
UNSUPPORTED_COMMAND
This build declares no verb matching the typed name.
Safe next action: Run `volli help` and choose one of the commands or topics it lists.
WRONG_DOOR
The verb exists, but the shell is not the surface that executes it.
Safe next action: Use the surface named in the refusal; if tool availability is unknown, inspect the Session Runtime Brief or `volli help <verb>` first.
FORBIDDEN_ACTOR
The verb is on this surface, and this caller is not one the project's policy lets run it. Coordination-tier verbs want an authenticated Volli Session; a process that merely runs as your user is not one.
Safe next action: Run the command from inside a Volli Session. If you already are, the project's per-actor policy withholds this verb and only a person can widen it in Settings — do not work around the refusal.
APP_UNREACHABLE
The local desktop host or one of its required runtimes could not answer.
Safe next action: Run `volli app launch`, wait for readiness, then retry the same command once.
DB_UNAVAILABLE
The app could not open the durable local database.
Safe next action: Open the Volli app and inspect its database error before retrying the command.
PROJECT_REQUIRED
The verb needs a Project, but the context ladder resolved none.
Safe next action: Pass `--project <name|prefix|path>` or run from a registered Project directory.
PROJECT_NOT_FOUND
The selected Project no longer exists or does not match a registered Project.
Safe next action: Run `volli project list`, then retry with a printed Project name, prefix, or path.
AMBIGUOUS_PROJECT
More than one registered Project matches the selector.
Safe next action: Retry with the exact Project path printed in the refusal.
TICKET_NOT_FOUND
No live Ticket matches the supplied Display ID in the resolved Project context.
Safe next action: Run `volli ticket list` in the intended Project and retry with a printed Display ID.
AMBIGUOUS_TICKET
The Display ID matches Tickets in more than one Project.
Safe next action: Resolve the intended Project explicitly, then retry the Ticket verb.
SESSION_NOT_FOUND
The supplied or attributed Session identity is stale, missing, or unresolved.
Safe next action: Run `volli session list` and use a current printed handle; for current-Session verbs, start from a live Volli Session.
AMBIGUOUS_CONTEXT
The context ladder found more than one equally valid target.
Safe next action: Pass the exact Project or Ticket selector requested by the refusal.
CONTEXT_REQUIRED
The verb needs Project, Ticket, or Session context that no safe fallback can infer.
Safe next action: Run `volli identify`, then supply the missing explicit selector or use a live Volli Session.
CONTEXT_MISMATCH
Explicit context conflicts with the Session or directory context Volli resolved.
Safe next action: Run `volli identify` and retry from the intended Session or with matching explicit context.
BODY_MATCH_FAILED
An exact Ticket Body edit found zero or multiple matches, so applying it could clobber newer prose.
Safe next action: Read the fresh Ticket Body, choose text that appears exactly once, and retry the edit.
INVALID_COLUMN
The supplied board column is outside the accepted column vocabulary.
Safe next action: Use a column named in the refusal or in `volli help ticket move`.
INVALID_PRIORITY
The supplied priority is outside the accepted priority vocabulary.
Safe next action: Use `low`, `medium`, or `high` and retry.
ARCHIVED_TICKET
The target Ticket is archived, so ordinary Ticket mutations are closed.
Safe next action: Open the Ticket in the app and restore it before retrying, or choose a live Ticket.
SESSION_ENDED
The target Session attachment has ended and cannot accept this live mutation.
Safe next action: Open or start a live Session, then repeat the action against that Session.
MODEL_REQUIRED
No runnable default model or explicit model was available for Session start.
Safe next action: Configure a default in Model Access or pass a model printed by `volli model list`.
MODEL_UNAVAILABLE
The requested model, provider sign-in, or reasoning level is not runnable now.
Safe next action: Run `volli model list`, then retry with an available printed model and reasoning level.
PREFIX_CONFLICT
A Project ticket prefix conflicts with another registered Project.
Safe next action: Resolve the duplicate prefix in Project Settings before retrying.
FILE_READ_FAILED
A CLI file argument could not be read safely before the request was sent.
Safe next action: Check the named path and permissions, or pass the content inline, then retry.
MUTATION_FAILED
The operation failed without enough durable outcome evidence for an automatic retry.
Safe next action: Unknown. Inspect current durable state before deciding whether a retry is safe.
RESPONSE_TOO_LARGE
The app answered, but the answer exceeded the CLI's 4 MiB response limit, so the CLI stopped reading it.
Safe next action: Narrow the request with the verb's own filters (see `volli help <verb>`) and retry.
SOCKET_PROTOCOL
The CLI connected to the app but the versioned request or response exchange was invalid.
Safe next action: Run `volli help changes` and confirm the CLI bundle and running app come from a compatible build before retrying.
TIMEOUT
The app accepted the connection but did not produce an outcome within the command's bound.
Safe next action: Inspect the current Ticket or Session state before deciding whether one retry is safe.
For UI problems, see Troubleshooting.