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 only if you enroll agents through the Wazuh manager API, or for agents with anti-tampering that remove themselves. Wazuh 5.x agents enroll and connect on 1517/TCP.

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

For a Wazuh 5.0 agent:

# nc -zv <WAZUH_MANAGER_ADDRESS> 1517

For a Wazuh 4.x agent:

# nc -zv <WAZUH_MANAGER_ADDRESS> 1514
# nc -zv <WAZUH_MANAGER_ADDRESS> 1515
# nc -zv <WAZUH_MANAGER_ADDRESS> 55000

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

For a Wazuh 5.0 agent:

Connection to <WAZUH_MANAGER_ADDRESS> 1517 port [tcp/*] succeeded!

For a Wazuh 4.x agent:

Connection to <WAZUH_MANAGER_ADDRESS> 1514 port [tcp/*] succeeded!
Connection to <WAZUH_MANAGER_ADDRESS> 1515 port [tcp/*] succeeded!
Connection to <WAZUH_MANAGER_ADDRESS> 55000 port [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_ADDRESS>", 1517)

For a Wazuh 4.x agent:

> (new-object Net.Sockets.TcpClient).Connect("<WAZUH_MANAGER_ADDRESS>", 1514)
> (new-object Net.Sockets.TcpClient).Connect("<WAZUH_MANAGER_ADDRESS>", 1515)
> (new-object Net.Sockets.TcpClient).Connect("<WAZUH_MANAGER_ADDRESS>", 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 0.0.0.0, which accepts connections from any host. If either one is set to 127.0.0.1, the listener 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'.

This log applies to Wazuh 4.x agents. For Wazuh 5.0 agents, the Wazuh manager logs nothing. Check the Wazuh agent log instead:

2026/10/27 22:38:31 wazuh-agentd:https-client: ERROR: https_client: the manager refused this request's credential (401, invalid_signature); keeping the current identity and retrying.

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

/etc/wazuh-manager/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 client key stored in the Wazuh manager /etc/wazuh-manager/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:

2026/10/27 22:41:24 wazuh-agentd: ERROR: Enrollment rejected by the manager: duplicate agent. Duplicate name

Wazuh manager log:

2026/10/27 22:41:23 wazuh-manager-authd: WARNING: Duplicate name '<AGENT_NAME>', rejecting enrollment. Agent '<ID>' can't be replaced since it is not disconnected.

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 "/etc/wazuh-manager/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 /etc/wazuh-manager/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

Invalid password

If you enable password authentication for agent enrollment, the Wazuh agent may not be able to authenticate with the Wazuh manager if there's an invalid or missing password.

Location: Wazuh agent log file

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

Error log (wrong password):

2026/10/27 22:40:14 wazuh-agentd: ERROR: Enrollment rejected by the manager: the credential's signature was refused: Invalid client authentication. This will keep failing until the credential is corrected on the manager; the agent is keeping the one it has and retrying.

Error log (no password file):

2026/10/27 22:40:47 wazuh-agentd: INFO: No authentication password provided
2026/10/27 22:40:47 wazuh-agentd: INFO: Enrollment rejected by the manager: invalid_request: Invalid client authentication. Retrying.

Resolution:

  1. Ensure the same password is used by the Wazuh manager and the Wazuh agent

  2. Ensure that the authd.pass password file is in the /etc/wazuh-manager/ directory of the Wazuh manager and has the right permission. The file permissions should be set to 640, and the group should be wazuh-manager (root:wazuh-manager or wazuh-manager:wazuh-manager).

  3. If password authentication is not needed, it should be disabled in the <auth> section of the Wazuh manager /etc/wazuh-manager/wazuh-manager.conf file.