Error codes

NexoVirt attaches a stable code to certain errors instead of only a free-text message, so the same underlying failure always surfaces the same identifier no matter where it appears in the panel.

The NX-<AREA>-<NNNN> scheme

A code has two parts: an area (PVE, AGENT, EDITION, and so on) and a four-digit number, often borrowed from an HTTP status where one applies (NX-PVE-0404 for a Proxmox 404, for example). The catalog lives in code (App\Libraries\Log\ErrorCode) and is the single source of truth: this page is generated from it via php spark docs:error-codes (see the CLI reference), so it can never drift from what the panel actually returns.

Note

An error without a matching entry still gets a code, title of Unknown error, and a generic user message: the UI never has to null-check for a missing catalog entry.

Where codes show up

• Diagnostics page (/panel/diagnostics, admin-only): every recorded error_events row, with a View button for the full detail.
• Per-guest Activity tab: action failures (power, create, reinstall, delete, password reset) log their real error, code included.
• Error toasts: nxAlert(msg, type, detail) adds a Details link when a code/detail is present.
• Unified log (/panel/logs, admin-only): every mirrored event_log row, filterable by area/level.
• In-panel reference (/panel/logs/codes): the live version of the table below, rendered straight from the same catalog.

Catalog

Code	Area	Title	User-facing message	Likely cause	Fix
NX-PVE-0401	pve	Proxmox authentication/permission denied	The panel was denied by Proxmox (check the host credentials/permissions).	Proxmox returned HTTP 401 or 403.	Verify the host user/token and role assignment in Proxmox.
NX-PVE-0404	pve	Proxmox resource not found	The requested Proxmox resource was not found.	Proxmox returned HTTP 404: the node, VM, or storage may no longer exist.	Verify the resource still exists in Proxmox and refresh the inventory.
NX-PVE-0500	pve	Proxmox server error	Proxmox returned an internal server error.	Proxmox returned HTTP 5xx.	Check the Proxmox host logs for details; retry the operation.
NX-PVE-0502	pve	Could not connect to Proxmox	The panel could not reach the Proxmox host.	Connection refused or network unreachable (HTTP 502 / cURL connect error).	Confirm the host IP/port is correct, the firewall allows port 8006, and Proxmox VE is running.
NX-PVE-0504	pve	Proxmox request timed out	The Proxmox host did not respond in time.	HTTP 504 or a cURL timeout waiting for a Proxmox response.	Check the host load and network latency; increase the timeout if needed.
NX-AGENT-0001	agent	No active host agent	This action requires the NexoVirt agent to be running on the host.	The host has no registered agent, or the agent has not sent a heartbeat recently.	Go to Hosts → Set up agent and complete onboarding for this host.
NX-EDITION-0001	edition	Community Edition node limit reached	The Community Edition allows a limited number of nodes. Upgrade to add more.	Node count exceeds the limit enforced by the current edition license.	Remove unused hosts, or upgrade to a higher-tier NexoVirt edition.
NX-EDITION-0002	edition	Community Edition guest limit reached, new guests disabled	The Community Edition guest limit has been reached. Upgrade to create more guests.	Guest count is at or over the per-edition cap.	Delete unused guests, or upgrade to a higher-tier NexoVirt edition.

Tip

The NX-EDITION-* codes are a soft degrade, not a hard block: the panel logs the event and keeps working under Community Edition limits rather than bricking the install. See Editions & licensing.

The catalog grows as new areas are wired up, codes are added only where they earn their keep, not speculatively. If you hit an error without a code, it is simply not catalogued yet; the panel’s free-text message and the unified log still capture the real cause.