Error reference

Every failure Agentarivm reports carries a stable code. The CLI prints it as code: message, the API returns it in the body, and the app branches on it. The message describes the moment; the code is what you can look up, search for, and quote in a bug report.

There are two families of code here, and knowing which one you are holding saves a search:

• API error codes — everything from Transport and authentication down to Review and merge. Something was refused, and this is why. Every code the manager can return is listed.
• Task failure reasons — the last section. A task ran and ended in failed, and this is why it stopped. These are not API error codes and never appear in a response body; they are how a task explains itself after the fact.

Every row is linkable: https://agentarivm.com/docs/errors/#repo_config_invalid goes straight to its line, and that is the form the CLI and the app print. If you are filing an issue, quoting the code is the single most useful thing you can include.

Transport and authentication

Code	What it means
unauthorized	No usable credential was presented. From the app, this normally means the device certificate was not sent or is not trusted — re-check that both the CA and the .p12 are installed, and that the CA is turned on under Certificate Trust Settings on iOS.
forbidden	Authenticated, but not allowed to do this.
device_revoked	This device was revoked with agentarivm devices revoke. Pair it again to restore access.
pairing_code_invalid	The code does not match. Codes are single-use and case-insensitive; a mistyped character gives this.
pairing_code_expired	The code was valid but timed out. Mint a fresh one with agentarivm pair.
pairing_code_used	The code was already redeemed. Codes are never accepted twice, deliberately.
rate_limited	Too many attempts too quickly. This mostly guards pairing, where guessing is the attack.
service_starting	The manager is up but still reconciling with the machine. Everything except health answers this until startup finishes; it clears on its own within seconds.

Generic

Code	What it means
validation_failed	The request or the configuration did not match the schema. The message names the field. For config, agentarivm config check gives the same answer without starting anything.
not_found	The thing named does not exist here.
conflict	The request contradicts the current state.
internal	A bug, or something genuinely unexpected. Worth reporting with the surrounding log lines.
idempotency_key_reused	The same idempotency key was sent with a different body — usually a client retrying a changed request rather than the original.

Projects

Code	What it means
invalid_repo_identity	The repository is not owner/repo, or does not resolve on GitHub.
insufficient_permission	The authenticated GitHub account cannot do this on that repository. Check with gh auth status which account the manager runs as — agentarivm doctor reports it too.
repo_already_registered	That repository is already a project here.
destination_exists	Something is already at the path the clone would occupy.
clone_failed	git clone failed. Almost always credentials or reachability; the message carries git’s own words.
project_not_ready	The project is still cloning or provisioning, or its last attempt failed. agentarivm project list shows which.
project_in_use	It cannot be removed while tasks are still attached to it.
unknown_setup_profile	The project names a setupProfile that the config does not define.
unknown_component	The task names a component the project does not declare.
repo_config_invalid	The repository’s own .agentarivm.yml exists and this manager will not act on it. The message says which part; a file that is nearly right is refused rather than half-applied.
provision_failed	The repository’s setup.provision commands ran and failed.

Tasks

Code	What it means
invalid_transition	The task cannot move from its current state to the requested one.
branch_collision	The branch the task would create already exists.
worktree_collision	The worktree path is already occupied. agentarivm reconcile clears entries the database and disk disagree about.
missing_secret_file	A file the setup profile copies into the worktree is not where the config says it is.
setup_failed	The workspace setup commands failed before the agent started.
agent_exited_unexpectedly	The agent process died without reporting. The task log is the place to look; a missing or invalid Claude credential is the most common cause, and agentarivm doctor reports that directly.
task_not_stoppable	Nothing is running to stop.
agent_not_running	Nothing on this task can be talked to. Three things produce it, and the message says which: the task has ended (stopped, failed, merged or cleaned_up), so there is nobody to read it; the agent could not be resumed — no conversation on disk, or the engine it ran on is no longer configured; or a caller that does not resume found no live process. An exited agent on its own is not this: sending a message resumes one first, and every manager restart leaves an exited agent behind.
agent_busy	The agent is mid-turn, so the message was queued rather than delivered. Not an error so much as a description.
prompt_not_pending	The agent is not waiting on a prompt, so there is nothing to answer.
engine_not_configured	The request named an agent engine this deployment has no engines: entry for. The details list what is configured.
engine_not_installed	The engine has an engines: entry, but its executable does not resolve on the manager, so a task on it would die at launch. Install it, or set an absolute path; agentarivm doctor shows what it found.
model_not_allowed	The requested model is not in the chosen engine’s allowedModels.
effort_not_allowed	The requested reasoning effort is not permitted by the config.
base_branch_not_allowed	The requested base branch is not in the project’s allowed list. This is a guard, not a bug: it stops an agent branching from somewhere it should not.

External systems

Code	What it means
agent_unavailable	The engine’s binary could not be run, or died before saying anything. Under a service the PATH is minimal — agentarivm doctor resolves the executables the way the daemon will, which is the fastest way to see the difference.
github_unavailable	gh failed or GitHub did not answer.
git_failed	A git command failed; the message carries git’s own output.

Review and merge

Code	What it means
merge_head_moved	The pull request moved between reading it and merging. Nothing was merged — read it again.
not_mergeable	GitHub says it cannot be merged, usually a conflict.
pull_request_is_draft	Distinct from not_mergeable: nothing is wrong, it is simply not ready.
checks_not_passing	Required checks have not passed.
cleanup_blocked	The worktree cannot be removed yet — uncommitted work, or a process still holding it.

Task failure reasons

A task that ends in failed carries a reason, shown under the task in the app and in the timeline entry that failed it. When a request refused something along the way — setup, git, GitHub — that reason is one of the API error codes above, recorded as-is. When nothing refused anything and the run simply stopped, it is one of these.

agent_exited_unexpectedly is the one code that appears in both namespaces: it is an API error code and a task failure reason, for the same event.

Reason	What it means
agent_launch_timeout	The task sat in starting for longer than task.launchTimeoutMinutes (default 5) without the agent ever producing a first response. Nearly always an engine binary that cannot run under the daemon’s PATH, or a credential that has expired; agentarivm doctor reports both, per engine. The longer version.
agent_reported_failure	The agent gave up and said so, by running agentarivm fail --message "…" from inside its worktree. The message is the agent’s own words, and is usually the most informative thing on this page.
agent_task_failed	The agent session ended in failure without leaving a reason. The task log is the only place left to look.
agent_task_missing	The task was running and the process supervising it is gone, with no record of how it ended — the manager was killed, or the machine rebooted, mid-task.
manager_restarted	The manager restarted while the task was still being prepared. queued and preparing live entirely in memory, so there is nothing to resume and retrying silently would risk starting an agent on a half-built worktree. Start it again; the worktree is kept either way.

Reporting one

If a code sends you here and this page did not help, that is worth knowing about — a code whose entry does not answer the question is a documentation bug in its own right. Include the code, the version from agentarivm --version, and the surrounding lines from the manager log.