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.