Troubleshooting

We recommend checking the logs on the Wazuh manager and Wazuh agent for errors when a Wazuh agent fails to enroll. The location of the Wazuh manager log file is /var/wazuh-manager/logs/wazuh-manager.log. The location of the Wazuh agent log file is dependent on the operating system:

Operating system	Wazuh agent log file
Linux/Unix	`/var/ossec/logs/ossec.log`
macOS	`/Library/Ossec/logs/ossec.log`
Windows 64-bit	`C:\Program Files (x86)\ossec-agent\ossec.log`
Windows 32-bit	`C:\Program Files\ossec-agent\ossec.log`

In the list below, you can access the different cases included in this troubleshooting section:

Verifying communication with the Wazuh manager

In some scenarios, the Wazuh agent may be unable to enroll or establish a connection with the Wazuh manager because the necessary ports on the Wazuh manager are unreachable.

The default ports on the Wazuh manager depend on the agent version:

Wazuh 5.0 agents: 1517/TCP (HTTPS) - used for both enrollment and agent communication.
Wazuh 4.x agents: 1515/TCP for enrollment and 1514/TCP for agent communication.
55000/TCP for enrollment via Wazuh manager API (both agent versions).

On Linux and macOS systems (with netcat installed) open a terminal and run the following commands. Replace <WAZUH_MANAGER_IP_ADDRESS> with your Wazuh manager IP address or fully qualified domain name (FQDN).

For a Wazuh 5.0 agent:

# nc -zv <WAZUH_MANAGER_IP_ADDRESS> 1517 55000

For a Wazuh 4.x agent:

# nc -zv <WAZUH_MANAGER_IP_ADDRESS> 1514 1515 55000

If there is connectivity, the output should be a connection success message:

Connection to <WAZUH_MANAGER_IP_ADDRESS> port 1517 [tcp] succeeded!
Connection to <WAZUH_MANAGER_IP_ADDRESS> port 1514 [tcp] succeeded!
Connection to <WAZUH_MANAGER_IP_ADDRESS> port 1515 [tcp] succeeded!
Connection to <WAZUH_MANAGER_IP_ADDRESS> port 55000 [tcp] succeeded!

On Windows, open a PowerShell terminal and run the following commands:

For a Wazuh 5.0 agent:

> (new-object Net.Sockets.TcpClient).Connect("<WAZUH_MANAGER_IP>", 1517)
> (new-object Net.Sockets.TcpClient).Connect("<WAZUH_MANAGER_IP>", 55000)

For a Wazuh 4.x agent:

> (new-object Net.Sockets.TcpClient).Connect("<WAZUH_MANAGER_IP>", 1514)
> (new-object Net.Sockets.TcpClient).Connect("<WAZUH_MANAGER_IP>", 1515)
> (new-object Net.Sockets.TcpClient).Connect("<WAZUH_MANAGER_IP>", 55000)

If there is connectivity, there is no output. Otherwise, an error is shown:

A connection attempt failed because the connected party did not properly respond after a period of time (...)

Note

If ports appear reachable at the network level but the connection still fails, check whether the manager's remoted listener is bound to the loopback interface only. Both <remote><https><bind_addr> (1517) and <remote><legacy><local_ip> (1514) in wazuh-manager.conf default to 127.0.0.1, which rejects connections from any other host. Set them to 0.0.0.0 to accept remote agents.

Authentication error

The client.keys file stores the data used to authenticate the Wazuh agent and the Wazuh manager. The Wazuh agent may be unable to authenticate with the Wazuh manager if the client.keys on the Wazuh manager and the Wazuh agent are different.

Location: Wazuh manager log file at /var/wazuh-manager/logs/wazuh-manager.log.

Error log:

2026/10/04 22:44:48 wazuh-manager-remoted: WARNING: (1404): Authentication error. Wrong key or corrupt payload. Message received from agent '007' at 'any'.

Resolution: Ensure that the client key on the Wazuh agent matches the key in the Wazuh manager client.keys file. You can find the client.keys key file at the following locations:

Endpoint	Location
Wazuh manager	`/var/wazuh-manager/etc/client.keys`
Linux/Unix	`/var/ossec/etc/client.keys`
macOS	`/Library/Ossec/etc/client.keys`
Windows	`"C:\Program Files (x86)\ossec-agent\client.keys"`

Also, verify that each agent has a unique agent key stored in the Wazuh manager /var/wazuh-manager/etc/client.keys file. Duplicate keys can arise if you previously deleted agents with the highest IDs or copied the client.keys file between agents.

Invalid agent name for enrollment

Each Wazuh agent must have a unique name before successfully enrolling in the Wazuh manager. If you do not specify a Wazuh agent name during the deployment process, Wazuh will use the endpoint's hostname. If two or more endpoints have the same hostname, the Wazuh agent enrollment will not be successful.

Location: Wazuh agent log file

Refer to the table in the Troubleshooting section for the Wazuh agent log file location.

Error log:

2022/01/26 08:59:10 wazuh-agentd: INFO: Using agent name as: localhost.localdomain
2022/01/26 08:59:10 wazuh-agentd: INFO: Waiting for server reply
2022/01/26 08:59:10 wazuh-agentd: ERROR: Invalid agent name: localhost.localdomain (from manager)
2022/01/26 08:59:10 wazuh-agentd: ERROR: Unable to add agent (from manager)

Resolution: Ensure the Wazuh agent hostname is unique and does not match an already enrolled agent. Alternatively, specify a unique agent name in the <client><enrollment><agent_name> section of the Wazuh agent ossec.conf file. You can find the ossec.conf file at the following locations:

Linux/Unix endpoints - /var/ossec/etc/ossec.conf
macOS endpoint - /Library/Ossec/etc/ossec.conf
Windows endpoints - C:\Program Files (x86)\ossec-agent\ossec.conf

<client>
     ...
     <enrollment>
         <agent_name>EXAMPLE_NAME</agent_name>
         ...
     </enrollment>
 </client>

Unable to read CA certificate file

The Wazuh agent may not be able to authenticate with the Wazuh manager if the root certificate authority is missing on either the Wazuh manager or the Wazuh agent. This applies when additional security options such as Wazuh manager identity verification and Wazuh agent identity verification are used.

Location: Wazuh manager log file at /var/wazuh-manager/logs/wazuh-manager.log.

Error log:

2026/07/06 12:37:28 wazuh-manager-authd: ERROR: Unable to read CA certificate file "/var/wazuh-manager/etc/rootCA.pem"
2026/07/06 12:37:28 wazuh-manager-authd: ERROR: SSL error. Exiting.

Resolution: Ensure the certificate authority file is in the location specified in the <ssl_agent_ca> section of the Wazuh manager /var/wazuh-manager/etc/wazuh-manager.conf file.

Location: Wazuh agent log file

Refer to the table in the Troubleshooting section for the Wazuh agent log file location.

Error log:

2026/10/01 23:52:50 wazuh-agentd: ERROR: (4118): <ssl><verification_mode> is not 'none' but <certificate_authorities> is missing or unreadable: '/var/ossec/etc/rootCA.pem'.
2026/10/01 23:52:50 wazuh-agentd: ERROR: (1215): No client configured. Exiting.

Resolution:

Wazuh 5.0 agents: Ensure the certificate authority file exists and is readable at the path set in <ssl><certificate_authorities> in the Wazuh agent configuration file (ossec.conf). If <certificate_authorities> is not set, the Wazuh agent uses the trust anchor etc/certs/root-ca.pem in its installation directory, which is installed when the Wazuh agent enrolls with an enrollment token.
Wazuh 4.x agents: Ensure the certificate authority file is in the location specified in the <server_ca_path> section of the Wazuh agent configuration file (ossec.conf).

You can find the ossec.conf file at the following locations:

Linux/Unix endpoints - /var/ossec/etc/ossec.conf
macOS endpoint - /Library/Ossec/etc/ossec.conf
Windows endpoints - C:\Program Files (x86)\ossec-agent\ossec.conf

Unable to read the client certificate or key

The Wazuh agent doesn't start if Wazuh agent identity verification is configured and the client certificate or key file is missing or unreadable.

Location: Wazuh agent log file

Refer to the table in the Troubleshooting section for the Wazuh agent log file location.

Error log:

2026/10/04 20:32:35 wazuh-agentd:https-client: ERROR: Config rejected: client certificate or key is not readable.
2026/10/04 20:32:35 wazuh-agentd: ERROR: https_client: failed to start (configuration rejected).
2026/10/04 20:32:35 wazuh-agentd: CRITICAL: https_client: startup failed. Exiting.

Resolution: Ensure that the files set in <ssl><certificate> and <ssl><key> in the Wazuh agent configuration file (ossec.conf) exist and are readable by the Wazuh agent. Set <certificate> and <key> together. If only one is set, the Wazuh agent logs Config rejected: client certificate and key must be set together. You can find the ossec.conf file at the following locations:

Linux/Unix endpoints - /var/ossec/etc/ossec.conf
macOS endpoint - /Library/Ossec/etc/ossec.conf
Windows endpoints - C:\Program Files (x86)\ossec-agent\ossec.conf