# From an error message to the rule {#root}

@status:doc/work @audience:user

[p01] vibe's error messages name the rule they enforce. This page lists the messages you are likely to meet, what each means, and the shortest way out, in the order they tend to appear.

## How to read an error {#how-to-read}

[p02] An error has three parts: what vibe refused, why, and where the rule lives, as an address such as `spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-002#IDENTITY-TUPLE`. `vibe explain "<address>"` prints the rule and what implements it; the pages of this manual explain the mechanism behind it. Exit codes are stable for scripts: 1 for a general failure, 3 for a conflict-shaped refusal such as a malformed [managed block](../glossary/index.xml#managed-block), 5 when you declined a plan.

> [p03] **Exit code** — the malformed-block abort is conflict-shaped; reusing exit code `3` (package conflict) is the working assumption (§5).
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-012#SURF-EXIT-CODE>

## Installing {#install-errors}

[p04]
| Message | What it means | Way out | Rule |
| --- | --- | --- | --- |
| `package … is already installed at version … — use vibe update instead` | the coordinate is already in the lock file with the same content | `vibe update <coordinate>` to move it, `vibe list` to look | `PROP-011#UPDATE-MOVES-LOCK` |
| `content drift on …: lockfile pins sha256:… but the source served sha256:…` | the bytes served differ from the bytes the lock file remembered: a re-tagged version, a broken mirror or an override | find out which; re-pin by uninstall and install, drop the mirror, or record the override; never edit the lock file | `PROP-002#EFF-FORCE-PUSH-CAUGHT` |
| `malformed <vibevm> block in …` | an instruction file has two markers of a kind, an opener without a closer, or a closer first | repair the file so exactly one ordered pair remains; `vibe check` finds it before the next install | `PROP-012#CLASS-MALFORMED` |
| `the materialised vibedeps/ tree is incomplete — … slot(s) missing` | a package the lock file pins has no folder on disk and the regeneration mode cannot conjure it | `vibe reinstall --force` to fetch it again | `PROP-009#REINSTALL-FORCE` |
| `package declares a [boot_snippet].source … that does not exist in the package` | the package's manifest points at a snippet file it does not ship | report it to the package's author; pin an earlier version meanwhile | `PROP-009#SCHEMA-BOOT-SNIPPET` |
| `user declined the install plan` | you answered no; nothing was written | nothing to fix | `PROP-009#PLAN-UNIT` |
| `package … is not installed` | `vibe uninstall` named a coordinate the lock file does not hold | `vibe list`; check the spelling | — |

## Resolving {#resolution-errors}

[p05]
| Message | What it means | Way out | Rule |
| --- | --- | --- | --- |
| `package … is not in the registry` | every configured registry answered that it has no such package | check the coordinate and the registries; `vibe search` to find it | `PROP-002#REGISTRY-WALK-ORDER` |
| `no version of … matches …` | the package exists but no published version satisfies the constraint | widen the constraint or ask for a version that exists | `PROP-000#CF-RANGE` |
| `package A needs C ^1 but B needs C ^2 …` | two constraints on one package cannot both hold | the fix ladder on the questions page: widen, update, override, fork | `PROP-002#OVERRIDE-SHORT-CIRCUIT` |
| `no registry configured …` | the manifest has no `[[registry]]` and no `--registry` was passed | `vibe registry add`, or seed from `~/.vibe/registry.toml` | `PROP-010#INIT-SEEDS` |
| an offline error naming a missing coordinate | `--offline` was set and the store does not hold the package | go online once, or `vibe cache add` it from a machine that is | `PROP-010#OFFLINE-HARD-ERROR` |

## Fetching {#git-errors}

[p06]
| Message | What it means | Way out | Rule |
| --- | --- | --- | --- |
| `the git executable is not available on PATH` | vibe shells out to the system git for every fetch and found none | install git and open a new terminal | `PROP-001#root` |
| `remote repository … not found (does it exist? is access granted?)` | the repository address is wrong or your credentials lack read access | check the registry's address and its authentication regime | `PROP-002#AUTH-REGIMES` |
| `ssh authentication failed for …` | the host answered but rejected your key | load the key into your agent; check the registry's `auth` | `PROP-002#ROW-AUTH-SSH` |
| `unable to reach … (network or DNS error)` | no route to the host | check the network, or work from the store with `--offline` | `PROP-010#OFFLINE-FLAG` |
| `branch / ref … not found on …` | the git source names a tag, branch or commit the repository does not have | fix the reference in the manifest | `PROP-002#ROW-GS-TAG-MEANING` |
| a mirror served different bytes | the mirror is out of date or tampered with | remove the mirror; the canonical registry is tried next | `PROP-002#MIRROR-INTEGRITY-MANDATORY` |

## Publishing {#publish-errors}

[p07]
| Message | What it means | Way out | Rule |
| --- | --- | --- | --- |
| `publish refused: no token available for host …` | no publish token in the environment or under `~/.vibe/` | place the token where the settings page says; never in the repository | `PROP-000#token-secrecy` |
| `publish refused: token lacks repo:create permission …` | the token cannot create repositories in the organisation | a token with the right scope, or `--repo-url` to an existing repository | `PROP-002#SHAPE-OWN-REPO` |
| `publish refused: tag … already exists on …` | the version was published before | bump the version; published versions never move | `PROP-002#IDENTITY-CONSEQUENCE` |
| `publish refused: source directory … does not look like a vibevm package` | the folder has no manifest with a `[package]` table | publish the package's root, or add the table | `PROP-007#PACKAGE-XOR-PROJECT` |
| `publish refused: organization … does not exist on …` or `no push access` | the registry's organisation or your rights on it | check the registry address and the token's owner | `PROP-002#REG-FIELD-URL` |

## Running the lifecycle {#lifecycle-errors}

[p08]
| Message | What it means | Way out | Rule |
| --- | --- | --- | --- |
| a contribution reported `fail` and the chain stopped | one step of a phase failed; the phases before it kept their results | read the contribution's id and output in the run's narration; `vibe extensions` shows where it came from | `PROP-054#FAILURE-BY-PHASE` |
| a parked agent task | a step needs an agent and vibe runs under one; the task waits in the outbox | the hosting agent performs it and re-runs the same command | `PROP-054#AGENT-HANDSHAKE` |
| `undeploy` refused a path | a file a receipt owns changed after deployment | decide by hand; vibe will not delete edited work | `PROP-054#R8-DEPLOY-RUNTIME` |
| `clean` refused to run | no project at or above the current folder | run it inside a project | `PROP-053#CLEAN-NEEDS-A-PROJECT` |

## When the message is not vibe's {#edge-cases}

[p09] A message you do not find here is probably from a layer below: usually git. Run the command again with `VIBE_LOG=vibe_registry=debug,vibe_publish=debug` to see the underlying command line and its output. And when a message cites an address, the rule is one `vibe explain` away.

> [p10] PROP-001: Git-backed registry for `vibe-registry`
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-001#root>