# От сообщения об ошибке к правилу {#root}

@status:doc/work @audience:user

[p01] Сообщения об ошибках vibe называют правило, которое они применяют. Эта страница перечисляет сообщения, которые вы, скорее всего, встретите, что каждое значит и самый короткий выход, в том порядке, в котором они обычно появляются.

## Как читать ошибку {#how-to-read}

[p02] У ошибки три части: что vibe отказался делать, почему и где живёт правило, адресом вроде `spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-002#IDENTITY-TUPLE`. `vibe explain "<address>"` печатает правило и код, который за ним стоит; страницы этого руководства объясняют стоящий за ним механизм. Коды выхода стабильны для скриптов: 1 — общий сбой, 3 — отказ в форме конфликта, например испорченный [управляемый блок](../glossary/index.xml#managed-block), 5 — вы отклонили план.

> [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>

## Установка {#install-errors}

[p04]
| Сообщение | Что значит | Выход | Правило |
| --- | --- | --- | --- |
| `package … is already installed at version … — use vibe update instead` | координата уже есть в лок-файле с тем же содержимым | `vibe update <coordinate>`, чтобы сдвинуть её, `vibe list`, чтобы посмотреть | `PROP-011#UPDATE-MOVES-LOCK` |
| `content drift on …: lockfile pins sha256:… but the source served sha256:…` | отданные байты отличаются от тех, что помнил лок-файл: перетегированная версия, сломанное зеркало или переопределение | выясните, что именно; перепиньте через uninstall и install, уберите зеркало или запишите переопределение; лок-файл не правьте никогда | `PROP-002#EFF-FORCE-PUSH-CAUGHT` |
| `malformed <vibevm> block in …` | в файле инструкций два маркера одного вида, открывающий без закрывающего или закрывающий первым | почините файл, чтобы осталась ровно одна упорядоченная пара; `vibe check` находит это до следующей установки | `PROP-012#CLASS-MALFORMED` |
| `the materialised vibedeps/ tree is incomplete — … slot(s) missing` | у пакета, который закрепил лок-файл, нет папки на диске, и режим регенерации не может её наколдовать | `vibe reinstall --force`, чтобы скачать заново | `PROP-009#REINSTALL-FORCE` |
| `package declares a [boot_snippet].source … that does not exist in the package` | манифест пакета указывает на файл фрагмента, которого пакет не поставляет | сообщите автору пакета; пока закрепите более раннюю версию | `PROP-009#SCHEMA-BOOT-SNIPPET` |
| `user declined the install plan` | вы ответили «нет»; ничего не записано | чинить нечего | `PROP-009#PLAN-UNIT` |
| `package … is not installed` | `vibe uninstall` назвал координату, которой нет в лок-файле | `vibe list`; проверьте написание | — |

## Разрешение {#resolution-errors}

[p05]
| Сообщение | Что значит | Выход | Правило |
| --- | --- | --- | --- |
| `package … is not in the registry` | каждый настроенный реестр ответил, что такого пакета у него нет | проверьте координату и реестры; `vibe search`, чтобы найти | `PROP-002#REGISTRY-WALK-ORDER` |
| `no version of … matches …` | пакет существует, но ни одна опубликованная версия не удовлетворяет ограничению | расширьте ограничение или попросите версию, которая существует | `PROP-000#CF-RANGE` |
| `package A needs C ^1 but B needs C ^2 …` | два ограничения на один пакет не могут выполняться одновременно | лестница починки на странице вопросов: расширить, обновить, переопределить, форкнуть | `PROP-002#OVERRIDE-SHORT-CIRCUIT` |
| `no registry configured …` | в манифесте нет `[[registry]]`, и `--registry` не передан | `vibe registry add` или засев из `~/.vibe/registry.toml` | `PROP-010#INIT-SEEDS` |
| офлайн-ошибка с именем недостающей координаты | включён `--offline`, а в хранилище пакета нет | выйдите в сеть один раз или сделайте `vibe cache add` с машины, у которой сеть есть | `PROP-010#OFFLINE-HARD-ERROR` |

## Скачивание {#git-errors}

[p06]
| Сообщение | Что значит | Выход | Правило |
| --- | --- | --- | --- |
| `the git executable is not available on PATH` | vibe вызывает системный git для каждого скачивания и не нашёл его | установите git и откройте новый терминал | `PROP-001#root` |
| `remote repository … not found (does it exist? is access granted?)` | адрес репозитория неверен или у ваших учётных данных нет права чтения | проверьте адрес реестра и его режим аутентификации | `PROP-002#AUTH-REGIMES` |
| `ssh authentication failed for …` | хост ответил, но отверг ваш ключ | загрузите ключ в агент; проверьте `auth` реестра | `PROP-002#ROW-AUTH-SSH` |
| `unable to reach … (network or DNS error)` | до хоста нет маршрута | проверьте сеть или работайте из хранилища с `--offline` | `PROP-010#OFFLINE-FLAG` |
| `branch / ref … not found on …` | git-источник называет тег, ветку или коммит, которых в репозитории нет | исправьте ссылку в манифесте | `PROP-002#ROW-GS-TAG-MEANING` |
| зеркало отдало другие байты | зеркало устарело или подменено | уберите зеркало; следующим пробуется канонический реестр | `PROP-002#MIRROR-INTEGRITY-MANDATORY` |

## Публикация {#publish-errors}

[p07]
| Сообщение | Что значит | Выход | Правило |
| --- | --- | --- | --- |
| `publish refused: no token available for host …` | нет токена публикации ни в окружении, ни под `~/.vibe/` | положите токен туда, куда говорит страница настроек; никогда в репозиторий | `PROP-000#token-secrecy` |
| `publish refused: token lacks repo:create permission …` | токен не может создавать репозитории в организации | токен с нужной областью или `--repo-url` на существующий репозиторий | `PROP-002#SHAPE-OWN-REPO` |
| `publish refused: tag … already exists on …` | версия уже публиковалась | поднимите версию; опубликованные версии не двигаются | `PROP-002#IDENTITY-CONSEQUENCE` |
| `publish refused: source directory … does not look like a vibevm package` | в папке нет манифеста с таблицей `[package]` | публикуйте корень пакета или добавьте таблицу | `PROP-007#PACKAGE-XOR-PROJECT` |
| `publish refused: organization … does not exist on …` или `no push access` | организация реестра или ваши права на неё | проверьте адрес реестра и владельца токена | `PROP-002#REG-FIELD-URL` |

## Прогон жизненного цикла {#lifecycle-errors}

[p08]
| Сообщение | Что значит | Выход | Правило |
| --- | --- | --- | --- |
| вклад сообщил `fail`, и цепочка остановилась | один шаг фазы упал; фазы до него сохранили результаты | прочитайте идентификатор вклада и его вывод в повествовании прогона; `vibe extensions` показывает, откуда он взялся | `PROP-054#FAILURE-BY-PHASE` |
| отложенная задача агента | шагу нужен агент, и vibe работает под ним; задача ждёт в исходящих | агент-хозяин выполняет её и запускает ту же команду снова | `PROP-054#AGENT-HANDSHAKE` |
| `undeploy` отказался трогать путь | файл, которым владеет квитанция, изменился после выкладки | решите руками; vibe не удалит отредактированную работу | `PROP-054#R8-DEPLOY-RUNTIME` |
| `clean` отказался работать | нет проекта в текущей папке и выше | запустите внутри проекта | `PROP-053#CLEAN-NEEDS-A-PROJECT` |

## Когда сообщение не от vibe {#edge-cases}

[p09] Сообщение, которого здесь нет, скорее всего, пришло со слоя ниже: обычно от git. Запустите команду снова с `VIBE_LOG=vibe_registry=debug,vibe_publish=debug`, чтобы увидеть нижележащую командную строку и её вывод. А когда сообщение цитирует адрес, правило в одном `vibe explain` от вас.

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