# Error codes

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

> What an agent, hub or panel error code means and what to do.

An error code shows up in the deploy window, in server events and in the agent log. Each row has a permanent address like `/en/reference/errors/#agent-git_access_denied`: the first part is the group, the second is the code itself. Links from the panel lead to these addresses.

## Agent: command replies

| Code | What happened | What to do |
|---|---|---|
| `validation` (#agent-validation) | The agent rejected the project settings: a `nolay.toml` or form field, a name, a key or a value. The error text lists the fields. | Fix the listed fields in `nolay.toml` or in the project form and deploy again. |
| `invalid` (#agent-invalid) | The code source failed validation: a wrong repository address or branch, or an empty archive or one over 200 MB. | Check the address and branch, or upload the archive again. |
| `unsupported` (#agent-unsupported) | The agent cannot do this: it is older than the panel, the stack was not recognized, or the action is not available for this source. | Update the agent by running the install command again. If the stack was not recognized, add a Dockerfile or pick a builder by hand. |
| `internal` (#agent-internal) | Unexpected agent error while running the command. | Retry. If it happens again, send `journalctl -u nolay-agent -n 100` output to support. |
| `unknown_project` (#agent-unknown_project) | The agent does not know this project yet: the desired state has not reached the server. | Wait a minute and retry. If the server is offline, bring it back online first. |
| `project_suspended` (#agent-project_suspended) | Deploy refused: the project is suspended. The reason is in the error text. | Pay for the plan, free up room within the limit, or resume the project in the panel. |
| `fetch_failed` (#agent-fetch_failed) | The agent could not fetch the code: the repository or archive is unreachable. | Check the repository address and the server outgoing network, upload the archive again. |
| `git_access_denied` (#agent-git_access_denied) | No access to the repository. | For GitHub, connect the Nolay app to the repository. For other Git hosts add the `NOLAY_GIT_TOKEN` (HTTPS) or `NOLAY_GIT_SSH_KEY` (SSH) secret. |
| `git_ref_not_found` (#agent-git_ref_not_found) | Branch or tag not found. The error text names the default branch. | Fix the branch in the project settings. |
| `git_repo_empty` (#agent-git_repo_empty) | The repository has no commits. | Push the first commit and deploy again. |
| `logs_unavailable` (#agent-logs_unavailable) | The agent could not stream logs: there are no containers or Docker is not answering. | Check that the project is running and open the logs again. |
| `backups_unavailable` (#agent-backups_unavailable) | Backups are unavailable: the agent could not reach Docker at startup. | Check `systemctl status docker` and restart the agent: `systemctl restart nolay-agent`. |
| `no_secrets_key` (#agent-no_secrets_key) | The agent secrets encryption key is not available on the server. | Run the install command again: it restores `/etc/nolay/agent.key` if it is missing. |
| `forbidden` (#agent-forbidden) | This service key cannot be shown or changed. | The action is not available for this service. |
| `service_stopped` (#agent-service_stopped) | The service is not running, so the password cannot be changed. | Start the service and retry. |
| `set_failed` (#agent-set_failed) | The password change command inside the service failed, the old password still works. | Details are in the server events. |
| `unknown_service` (#agent-unknown_service) | The agent has not started this service yet. | Wait for the service to start and retry. |
| `remove_failed` (#agent-remove_failed) | Removing the service failed. | Retry. If it does not help, check Docker on the server. |

## Hub: command delivery and connection

| Code | What happened | What to do |
|---|---|---|
| `agent_offline` (#hub-agent_offline) | The agent is not connected, the command was not sent. | Check the server: `systemctl status nolay-agent`. Retry once it is back online. |
| `not_delivered` (#hub-not_delivered) | The agent did not accept the command. | Retry in a minute. |
| `timeout` (#hub-timeout) | The agent did not answer in time. | Retry in a minute. If it keeps happening, check the server load and network. |
| `unsupported` (#hub-unsupported) | This agent version cannot do this action. | Update the agent by running the install command again. |
| `conflict` (#hub-conflict) | The current state does not allow the action, for example the tunnel is blocked by staff. | See the error text; for a block, contact support. |
| `unauthorized` (#hub-unauthorized) | The agent connected with a wrong or revoked token. | Delete the server in the panel, create it again and run the new install command. |
| `too_many_requests` (#hub-too_many_requests) | Too many connections from this address, the hub refuses for a while. | The agent reconnects on its own after a pause, nothing to do. |

## Agent connection close codes

| Code | What happened | What to do |
|---|---|---|
| `4000` (#ws-4000) | The server was deleted in the panel and the hub closed the connection. | If it was deleted by mistake, add it again and run the new install command. |
| `4001` (#ws-4001) | Another agent connected with the same ID. | Make sure the install command was not run on two servers. Each server has its own command. |
| `4003` (#ws-4003) | The token does not match the agent or was revoked. | Create the server in the panel again and run the new install command. |
| `4004` (#ws-4004) | The tunnel is not enabled for this server. | Turn on the tunnel in the server settings. |
| `4008` (#ws-4008) | The agent did not introduce itself in time or cannot keep up reading messages. | The agent reconnects on its own. If it repeats, check the server load. |

## Archive upload

| Code | What happened | What to do |
|---|---|---|
| `too_large` (#upload-too_large) | The archive is larger than 200 MB. | Remove builds and dependencies such as `node_modules` from the archive. |
| `unsupported` (#upload-unsupported) | The archive format is not supported. RAR and 7z are not accepted. | Pack the code as zip or tar.gz. |
| `empty` (#upload-empty) | The file is empty. | Choose an archive with the project code. |
| `too_many` (#upload-too_many) | Three uploads are already in progress. | Wait for the previous archive to deploy or retry later. |
| `no_space` (#upload-no_space) | The upload storage has no room right now. | Try again in a few minutes. |
| `forbidden` (#upload-forbidden) | Only organization owners and admins can upload archives. | Ask the owner for the admin role. |
| `network` (#upload-network) | The connection dropped during the upload. | Check the network and upload again. |

## Project suspension

| Code | What happened | What to do |
|---|---|---|
| `over_limit` (#suspend-over_limit) | The project is suspended: it is over the plan limit. | Move to a bigger plan or delete extra projects. |
| `subscription_expired` (#suspend-subscription_expired) | The project is suspended: the subscription is not paid. | Pay for the plan in Billing, the project resumes. |
| `operator` (#suspend-operator) | The project was stopped by Nolay staff. | Contact support. |

## Feed events

| Code | What happened | What to do |
|---|---|---|
| `deploy_failed` (#event-deploy_failed) | The deploy failed, the previous version keeps running. | Open the build log in the deploy window: the last error line usually names the cause. |
| `health_failed` (#event-health_failed) | The readiness check failed, the new version is not switched on. | Check the application port (`run.port`) and the `health.path`. |
| `container_died` (#event-container_died) | The container exited abnormally. | Open the project logs: the cause is in the last lines. |
| `worker_failed` (#event-worker_failed) | A background process failed to start. | Check the `workers.cmd` command and the project logs. |
| `cron_skipped` (#event-cron_skipped) | A scheduled job was skipped: the previous run is still going. | Make the interval longer or the job faster. |
| `backup_failed` (#event-backup_failed) | The backup failed. | Check the `NOLAY_S3_*` secrets and the server access to the storage. |
| `restore_failed` (#event-restore_failed) | Restore from backup failed. | Details are in the project events. |
| `service_failed` (#event-service_failed) | A catalog service failed to start. | Check free memory and disk on the server. |
| `disk_low` (#event-disk_low) | The server disk is over 85 percent full. | Remove old images with `docker image prune` or grow the disk. |
| `mem_high` (#event-mem_high) | Server memory is over 90 percent used. | Lower project limits or move to a server with more memory. |
| `agent_offline` (#event-agent_offline) | The agent has not answered for over 90 seconds. Projects keep running. | Check that the server is on and run `systemctl status nolay-agent`. |

## Pre-install check

| Code | What happened | What to do |
|---|---|---|
| `not-root` (#preflight-not-root) | The installer was run without root. | Run the command with `sudo`. |
| `arch` (#preflight-arch) | The CPU architecture is not supported. | Use an x86_64 server. |
| `arch-arm` (#preflight-arch-arm) | The server is ARM. An aarch64 build exists but is not tested live. | Prefer an x86_64 server. |
| `no-systemd` (#preflight-no-systemd) | The server has no systemd. | Use an Ubuntu LTS or Debian 12 image. |
| `os-unsupported` (#preflight-os-unsupported) | The operating system is not supported. | Reinstall the server with Ubuntu LTS or Debian 12 or newer. |
| `os-old` (#preflight-os-old) | The OS version is too old. | Use Ubuntu 22.04 or newer, or Debian 12 or newer. |
| `mem-low` (#preflight-mem-low) | Less than 1 GB of memory. | Pick a VPS plan with 1 GB of memory or more. |
| `disk-low` (#preflight-disk-low) | Less than 5 GB free on `/var/lib`. | Free up space or grow the disk. |
| `port-container` (#preflight-port-container) | Port 80 or 443 is held by a Docker container. | Stop that container: ports 80 and 443 are needed by the Nolay proxy. |
| `port-nginx` (#preflight-port-nginx) | Port 80 or 443 is held by a web server. Apache and others get the same kind of code: `port-apache2`, `port-httpd`. | Stop and disable that web server, or run the installer with `--fix`. |
| `panel-coolify` (#preflight-panel-coolify) | Another hosting panel was found. The others get the same kind of code: `panel-dokploy`, `panel-caprover`, `panel-plesk`, `panel-cpanel`, `panel-ispmanager`, `panel-aapanel`, `panel-hestiacp`. | Nolay does not install next to another panel. Use a clean server. |
| `net-hub` (#preflight-net-hub) | No access to `api.nolay.ru`. | Allow outgoing connections to port 443. The agent installs but stays offline until access works. |