Skip to content

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.

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.

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.