# Коды ошибок

URL: https://docs.nolay.ru/reference/errors/
Updated: 2026-09-23

> Что значит код ошибки агента, hub или панели и что сделать.

Код ошибки виден в окне деплоя, в событиях сервера и в журнале агента. У каждой строки постоянный адрес вида `/reference/errors/#agent-git_access_denied`: первая часть это группа, вторая сам код. На эти адреса ведут ссылки из панели.

## Агент: ответ на команду

| Код | Что случилось | Что делать |
|---|---|---|
| `validation` (#agent-validation) | Настройки проекта не прошли проверку агента: поле `nolay.toml` или формы, имя, ключ или значение. В тексте ошибки перечислены поля. | Исправьте названные поля в `nolay.toml` или в форме проекта и задеплойте снова. |
| `invalid` (#agent-invalid) | Источник кода не прошёл проверку: неверный адрес или ветка репозитория, либо архив пустой или больше 200 МБ. | Проверьте адрес и ветку или загрузите архив заново. |
| `unsupported` (#agent-unsupported) | Агент не умеет это действие: версия агента старше панели, стек не распознан или для этого источника действие недоступно. | Обновите агент повторным запуском команды установки. Если стек не распознан, добавьте Dockerfile или выберите сборщик вручную. |
| `internal` (#agent-internal) | Непредвиденная ошибка агента при выполнении команды. | Повторите действие. Если ошибка повторяется, пришлите в поддержку вывод `journalctl -u nolay-agent -n 100`. |
| `unknown_project` (#agent-unknown_project) | Агент ещё не знает этот проект: желаемое состояние не дошло до сервера. | Подождите минуту и повторите. Если сервер офлайн, сначала верните его на связь. |
| `project_suspended` (#agent-project_suspended) | Деплой отклонён: проект приостановлен. Причина в тексте ошибки. | Оплатите тариф, освободите место в лимите или возобновите проект в панели. |
| `fetch_failed` (#agent-fetch_failed) | Агент не смог получить код: репозиторий или архив недоступен. | Проверьте адрес репозитория и исходящую сеть сервера, архив загрузите заново. |
| `git_access_denied` (#agent-git_access_denied) | Нет доступа к репозиторию. | Для GitHub подключите приложение Nolay к репозиторию. Для другого Git добавьте секрет `NOLAY_GIT_TOKEN` (HTTPS) или `NOLAY_GIT_SSH_KEY` (SSH). |
| `git_ref_not_found` (#agent-git_ref_not_found) | Ветка или тег не найдены. В тексте ошибки указана ветка по умолчанию. | Исправьте ветку в настройках проекта. |
| `git_repo_empty` (#agent-git_repo_empty) | В репозитории нет ни одного коммита. | Отправьте первый коммит и задеплойте снова. |
| `logs_unavailable` (#agent-logs_unavailable) | Агент не смог отдать логи: контейнеров нет или Docker не отвечает. | Проверьте, что проект работает, и откройте логи снова. |
| `backups_unavailable` (#agent-backups_unavailable) | Бэкапы недоступны: при старте агент не подключился к Docker. | Проверьте `systemctl status docker` и перезапустите агент: `systemctl restart nolay-agent`. |
| `no_secrets_key` (#agent-no_secrets_key) | На сервере недоступен ключ шифрования секретов агента. | Запустите команду установки ещё раз: она восстановит `/etc/nolay/agent.key`, если его нет. |
| `forbidden` (#agent-forbidden) | Этот ключ сервиса нельзя показать или изменить. | Действие для этого сервиса недоступно. |
| `service_stopped` (#agent-service_stopped) | Сервис не запущен, поэтому пароль сменить нельзя. | Запустите сервис и повторите. |
| `set_failed` (#agent-set_failed) | Команда смены пароля внутри сервиса завершилась ошибкой, прежний пароль остался в силе. | Подробности в событиях сервера. |
| `unknown_service` (#agent-unknown_service) | Агент ещё не запустил этот сервис. | Дождитесь запуска сервиса и повторите. |
| `remove_failed` (#agent-remove_failed) | Удалить сервис не получилось. | Повторите. Если не помогло, проверьте Docker на сервере. |

## Hub: доставка команд и подключение

| Код | Что случилось | Что делать |
|---|---|---|
| `agent_offline` (#hub-agent_offline) | Агент не на связи, команда не отправлена. | Проверьте сервер: `systemctl status nolay-agent`. Когда он вернётся онлайн, повторите. |
| `not_delivered` (#hub-not_delivered) | Агент не принял команду. | Повторите через минуту. |
| `timeout` (#hub-timeout) | Агент не ответил вовремя. | Повторите через минуту. Если повторяется, проверьте нагрузку и сеть сервера. |
| `unsupported` (#hub-unsupported) | Версия агента не умеет это действие. | Обновите агент повторным запуском команды установки. |
| `conflict` (#hub-conflict) | Текущее состояние не позволяет действие, например туннель заблокирован администрацией. | Подробности в тексте ошибки, при блокировке напишите в поддержку. |
| `unauthorized` (#hub-unauthorized) | Агент подключился с неверным или отозванным токеном. | Удалите сервер в панели, создайте заново и выполните новую команду установки. |
| `too_many_requests` (#hub-too_many_requests) | Слишком много подключений с этого адреса, hub временно отказывает. | Агент подключится сам после паузы, делать ничего не нужно. |

## Закрытие соединения агента

| Код | Что случилось | Что делать |
|---|---|---|
| `4000` (#ws-4000) | Сервер удалён в панели, hub закрыл соединение. | Если сервер удалён по ошибке, добавьте его заново и выполните новую команду установки. |
| `4001` (#ws-4001) | С тем же идентификатором подключился другой агент. | Проверьте, что команду установки не запускали на двух серверах. У каждого сервера своя команда. |
| `4003` (#ws-4003) | Токен не подходит к агенту или отозван. | Создайте сервер в панели заново и выполните новую команду установки. |
| `4004` (#ws-4004) | Туннель для сервера не включён. | Включите туннель в настройках сервера. |
| `4008` (#ws-4008) | Агент не представился вовремя или не успевает читать сообщения. | Агент переподключится сам. Если повторяется, проверьте нагрузку сервера. |

## Загрузка архива

| Код | Что случилось | Что делать |
|---|---|---|
| `too_large` (#upload-too_large) | Архив больше 200 МБ. | Уберите из архива сборки и зависимости, например `node_modules`. |
| `unsupported` (#upload-unsupported) | Формат архива не поддерживается. RAR и 7z не принимаются. | Упакуйте код в zip или tar.gz. |
| `empty` (#upload-empty) | Файл пустой. | Выберите архив с кодом проекта. |
| `too_many` (#upload-too_many) | Уже идут три загрузки архивов. | Дождитесь деплоя предыдущего архива или повторите позже. |
| `no_space` (#upload-no_space) | В хранилище загрузок сейчас нет места. | Повторите через несколько минут. |
| `forbidden` (#upload-forbidden) | Загружать архивы могут владелец и администраторы организации. | Попросите владельца выдать вам роль администратора. |
| `network` (#upload-network) | Связь оборвалась во время загрузки. | Проверьте сеть и загрузите архив снова. |

## Приостановка проекта

| Код | Что случилось | Что делать |
|---|---|---|
| `over_limit` (#suspend-over_limit) | Проект приостановлен: он сверх лимита тарифа. | Перейдите на тариф больше или удалите лишние проекты. |
| `subscription_expired` (#suspend-subscription_expired) | Проект приостановлен: подписка не оплачена. | Оплатите тариф в разделе «Тариф», проект возобновится. |
| `operator` (#suspend-operator) | Проект остановлен администрацией Nolay. | Напишите в поддержку. |

## События в ленте

| Код | Что случилось | Что делать |
|---|---|---|
| `deploy_failed` (#event-deploy_failed) | Деплой завершился ошибкой, прежняя версия продолжает работать. | Откройте лог сборки в окне деплоя: последняя строка с ошибкой обычно называет причину. |
| `health_failed` (#event-health_failed) | Проверка готовности не прошла, новая версия не включена. | Проверьте порт приложения (`run.port`) и путь `health.path`. |
| `container_died` (#event-container_died) | Контейнер аварийно завершился. | Откройте логи проекта: причина в последних строках. |
| `worker_failed` (#event-worker_failed) | Фоновый процесс не запустился. | Проверьте команду `workers.cmd` и логи проекта. |
| `cron_skipped` (#event-cron_skipped) | Задача по расписанию пропущена: прошлый запуск ещё идёт. | Увеличьте интервал или ускорьте задачу. |
| `backup_failed` (#event-backup_failed) | Бэкап завершился ошибкой. | Проверьте секреты `NOLAY_S3_*` и доступ сервера к хранилищу. |
| `restore_failed` (#event-restore_failed) | Восстановление из бэкапа завершилось ошибкой. | Подробности в событиях проекта. |
| `service_failed` (#event-service_failed) | Сервис каталога не запустился. | Проверьте свободную память и диск сервера. |
| `disk_low` (#event-disk_low) | Диск сервера занят больше чем на 85 процентов. | Удалите старые образы командой `docker image prune` или увеличьте диск. |
| `mem_high` (#event-mem_high) | Память сервера занята больше чем на 90 процентов. | Уменьшите лимиты проектов или возьмите сервер с большей памятью. |
| `agent_offline` (#event-agent_offline) | Агент не выходит на связь больше 90 секунд. Проекты при этом продолжают работать. | Проверьте, что сервер включён, и выполните `systemctl status nolay-agent`. |

## Проверка перед установкой

| Код | Что случилось | Что делать |
|---|---|---|
| `not-root` (#preflight-not-root) | Установка запущена не от root. | Запустите команду через `sudo`. |
| `arch` (#preflight-arch) | Архитектура процессора не поддерживается. | Возьмите сервер x86_64. |
| `arch-arm` (#preflight-arch-arm) | Сервер на ARM. Сборка для aarch64 есть, но живьём не обкатана. | Для надёжности возьмите x86_64. |
| `no-systemd` (#preflight-no-systemd) | На сервере нет systemd. | Возьмите образ Ubuntu LTS или Debian 12. |
| `os-unsupported` (#preflight-os-unsupported) | Операционная система не поддерживается. | Переустановите сервер на Ubuntu LTS или Debian 12 и новее. |
| `os-old` (#preflight-os-old) | Версия системы слишком старая. | Возьмите Ubuntu 22.04 и новее или Debian 12 и новее. |
| `mem-low` (#preflight-mem-low) | Памяти меньше 1 ГБ. | Возьмите тариф VPS с 1 ГБ памяти и больше. |
| `disk-low` (#preflight-disk-low) | Свободно меньше 5 ГБ на `/var/lib`. | Освободите место или увеличьте диск. |
| `port-container` (#preflight-port-container) | Порт 80 или 443 занят контейнером Docker. | Остановите этот контейнер: порты 80 и 443 нужны прокси Nolay. |
| `port-nginx` (#preflight-port-nginx) | Порт 80 или 443 занят веб-сервером. Для apache и других код такой же: `port-apache2`, `port-httpd`. | Остановите и отключите этот веб-сервер или запустите установку с `--fix`. |
| `panel-coolify` (#preflight-panel-coolify) | На сервере найдена другая панель хостинга. Для остальных код такой же: `panel-dokploy`, `panel-caprover`, `panel-plesk`, `panel-cpanel`, `panel-ispmanager`, `panel-aapanel`, `panel-hestiacp`. | Nolay не ставится рядом с другой панелью. Возьмите чистый сервер. |
| `net-hub` (#preflight-net-hub) | Нет доступа к `api.nolay.ru`. | Откройте исходящие соединения на порт 443. Агент встанет, но будет офлайн, пока доступа нет. |