NexoVirt error code reference

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 and is the single source of truth: the table below is generated from it (the php spark docs:error-codes command exports the same catalog, see the CLI reference), and the panel shows the live version at /panel/logs/codes (the Error-code reference button on the Logs page).

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, 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 notifications: a failed action’s toast has a Details link when a code or detail is present.
• Logs (/panel/logs, admin-only): the unified event log, filterable by level, area and source.
• 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-AGENT-0001	agent	No active node agent	This action requires the NexoVirt agent to be running on the node.	The node has no registered agent or the agent has not sent a heartbeat recently.	Go to Nodes → Set up agent and complete the onboarding for this node.
NX-DYNDNS-0001	dyndns	DynDNS service unreachable	The NexoVirt DynDNS service could not be reached. Please try again in a minute.	license.endpoint unset, network error, or NexoVirtAdmin down.	Check license.endpoint in .env and outbound HTTPS.
NX-DYNDNS-0002	dyndns	DynDNS request refused	The NexoVirt DynDNS service refused the request.	NexoVirtAdmin returned an error code (see detail).	Follow the message (claim install, claim label, limit).
NX-DYNDNS-0003	dyndns	Install not claimed	Claim this install to your NexoVirt account first, then enable DynDNS.	The install license is not claimed to a NexoVirt account (or no license key is set).	Settings > Edition & license > Claim this install.
NX-DYNDNS-0004	dyndns	Node has no agent	DynDNS runs through the NexoVirt agent, which is installed on another node.	DynDNS runs through the node agent, which is installed on another node.	Enable DynDNS on the agent’s node.
NX-DYNDNS-0005	dyndns	Agent could not be configured	The node agent could not be configured for DynDNS. Check that the agent is online and current, then try again.	The dyndns_configure agent job failed or timed out; the Admin side was rolled back.	Check the agent is online and current (Update agent), then retry.
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 nodes 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.
NX-MIG-0001	migration	Migration pre-flight refused	The migration cannot start because a pre-flight check failed.	A required condition (version, reachability, storage, VMID, guest state) is not met.	Open the Migrate dialog again and resolve the failed checks.
NX-MIG-0002	migration	Migration transfer failed	The guest could not be transferred to the target node.	Token creation, the remote_migrate call or the PVE transfer task failed.	Check the job log and the source node task log, then retry.
NX-MIG-0003	migration	Migration finished with warnings	The guest was moved, but some follow-up steps need attention.	Applying the IP plan, port-forwards, records or safety-copy marking failed after the transfer.	Review the warnings in the job log and fix the listed items manually.
NX-PVE-0401	pve	Proxmox authentication/permission denied	The panel was denied by Proxmox (check the node credentials/permissions).	PVE returned HTTP 401 or 403.	Verify the node user/token and role assignment in Proxmox.
NX-PVE-0404	pve	Proxmox resource not found	The requested Proxmox resource was not found.	PVE 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.	PVE returned HTTP 5xx.	Check the Proxmox node logs for details; retry the operation.
NX-PVE-0502	pve	Could not connect to Proxmox	The panel could not reach the Proxmox node.	Connection refused or network unreachable (HTTP 502 / cURL connect error).	Confirm the node IP/port is correct, the firewall allows port 8006, and PVE is running.
NX-PVE-0504	pve	Proxmox request timed out	The Proxmox node did not respond in time.	HTTP 504 or cURL timeout waiting for a PVE response.	Check the node load and network latency; increase the timeout if needed.
NX-VPN-0001	vpn	VPN could not be applied on the node	The node agent could not apply the VPN configuration. Check that the agent is online and current, then try again.	The apply_wireguard agent job failed or timed out (wireguard-tools install, wg-quick, iptables).	Update the agent to 0.22.0, check the node can reach the Debian mirrors, retry from Settings > VPN.
NX-VPN-0002	vpn	VPN subnet conflict	The VPN subnet overlaps a network that is already in use.	A bridge, IP zone, SDN subnet, NAT range, client network or another node’s VPN subnet overlaps the VPN subnet, or no free /24 is left in the VPN range.	Pick a custom subnet or change the VPN range in Settings > VPN.
NX-VPN-0003	vpn	VPN device refused	The VPN device could not be created.	Device limit reached, too many requests, invalid name, or no VPN-enabled node is reachable for the owner.	Revoke an unused device, wait a minute, or enable the VPN on a node first.
NX-VPN-0004	vpn	Customer VPN needs Enterprise	Customer VPN devices are part of NexoVirt Enterprise.	A customer VPN action was requested on a Community Edition install.	Activate an Enterprise license in Settings > Edition & license.

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.