Agents and enrolment

The install command fails on the endpoint

The installers print enrolment refused (HTTP <code>): <message> (Linux, macOS) or enrolment refused: <message> (Windows).

Message	Cause	Fix
enrolment token invalid, expired, revoked or used up	The token is wrong, past its validity, revoked, or has enrolled its maximum number of machines	Create a new token (Agents → Add agents)
patch management is not enabled on this Theseus installation	--patching while the patch module is off (every token allows patching; only the installation can refuse it)	Enable it (ask us, or ./theseus modules enable patch), or run without --patching
This Theseus licence allows N agents. Ask your provider to raise the limit.	Licence limit reached	Remove unused agents, or ask us to raise the limit (licence)
"<name>" is already enrolled - remove it in Theseus first, or enrol this machine under another name (--name)	Another machine (or an earlier install of this one) has the name	Remove the old agent on the Agents page, or use --name
an agent named "<name>" already exists ...	Same, on the manager	Same
agent <id> is not registered as "<name>" on this Theseus installation ...	The machine holds an agent key from another installation, or its agent was deleted	Use --new-identity
this machine is already enrolled for patching with a different agent key	The Theseus agent's key changed (reinstalled OS, copied VM)	Remove the machine in Theseus first, then enrol
agent key proof does not match	The machine's agent key belongs to another agent	Use --new-identity
too many enrolment attempts from this address - try again later	20 requests in 10 minutes, or 5 failures, from one address	Wait (up to an hour after failures); stagger rollouts behind NAT
enrolment temporarily paused - try again later	More than 300 enrolments in an hour	Wait and retry
enrolment temporarily unavailable (manager not reachable)	The Wazuh manager is down	sudo ./theseus status on the server
run as root / run PowerShell as Administrator	Not elevated	Run with sudo / elevated PowerShell
unsupported distribution	Not Debian/Ubuntu or RHEL family	See supported endpoints
download of the monitoring component failed / cannot fetch the monitoring component's package signing key	The endpoint cannot reach the agent package site, packages.wazuh.com	Allow it, or use a proxy
the monitoring component could not be installed	The package manager failed; the lines under Details for support say why	Fix the package manager error (locks, disk, repositories), re-run
the monitoring component did not start	The agent service did not start	Run the command after Details for support and send us its output

curl fails before the installer runs

Error	Cause	Fix
Could not resolve host	The console's name does not resolve on the endpoint	DNS
Connection timed out	443 blocked between the endpoint and the server	Firewall
public key does not match pinned public key	A TLS-inspecting proxy, or a command from another stack	Exclude the console's address from inspection; use your console's command
SSL certificate problem	Internal CA, and the pin part was removed from the command	Use the command exactly as the console shows it

The agent is enrolled but never connects

Symptom. The machine is under Enrolled machines, but the Agents page shows Never connected or Lost contact.

Cause. The Wazuh agent cannot reach AGENT_HOST on TCP 1514.

Diagnose, on the endpoint:

sudo grep -A3 '<server>' /var/ossec/etc/ossec.conf      # the address and port it uses
sudo tail -n 50 /var/ossec/logs/ossec.log               # connection errors
nc -zv <agent host> 1514

Windows: C:\Program Files (x86)\ossec-agent\ossec.log, and Test-NetConnection <agent host> -Port 1514.

Fix.

• Open TCP 1514 inbound on the server (the core, with two servers) and outbound from endpoints.
• With a cloud gateway, 1514 must use its own TCP path, not the HTTP gateway (cloud gateways).
• With two servers, the agent address must be one endpoints can reach (details).

The agent shows "Disabled"

An administrator disabled it on the Agents page. Enable agent brings it back. See Disable, enable, remove.

The agent shows "Held by licence"

Cause. More agents than the licence allows, or the licence ended, expired or could not be renewed for 7 days (the stack then allows one agent). See Licence and agent limits.

Fix. Remove agents you no longer need, or have the licence raised or renewed. Held agents are released automatically within a few minutes of the licence having room. You cannot enable a held agent by hand while there is no room.

Licence expired or stale banner

Banner	Fix
Trial ended / Licence expired / Licence ended	Contact us
This stack has not reached its provider for 7 days	The stack cannot reach the control plane. Check theseus-node: sudo systemctl status theseus-node, sudo journalctl -u theseus-node -n 100, and outbound HTTPS (network). Once it reconnects the licence is renewed within minutes
No licence is installed	The licence has not been delivered: same checks as above. sudo ls -l /opt/theseus/runtime/license/
The licence could not be verified	Contact us

Nothing is deleted while the stack is limited.

The patching agent is offline

See Patching and Pallas.