Wazuh Agent Stuck in "Never Connected": Diagnosing Enrollment vs. Connection Failures
Reach 50,000+ security professionals
Sponsor a newsletter slot and put your brand in front of CISOs, engineers, and IT decision-makers.
A Wazuh agent showing Never Connected in the console has cleared the enrollment step, its key is registered in /var/ossec/etc/client.keys on both the agent and the manager, but it has never actually opened a working connection to the manager. Teams running fleet deployments through Ansible, Chef, or cloud init scripts frequently see a batch of Never Connected agents after a mass enrollment run, because the scripts enroll the keys correctly but skip the step that starts or restarts the wazuh-agent service. This guide isolates that case from the other four common root causes and provides the specific commands and log lines that confirm which cause applies before any fix is attempted. For background on building a Wazuh deployment with tuned detection rules, see this Wazuh false-positive reduction guide.
Root Causes: Why Never Connected Happens
Never Connected means one of five things, and they require different fixes.
Cause 1: wazuh-agent service was never started or restarted after enrollment. The most common cause in mass-enrollment scenarios. Registration writes the key to client.keys, but if the wazuh-agent daemon is not running (or was running before enrollment and was not restarted afterward), it never reads the new key and never attempts a connection. The agent stays perpetually in Never Connected.
Cause 2: Firewall blocks port 1514 from the agent to the manager. The agent needs an outbound path to the manager on TCP port 1514 (or UDP 1514 when using UDP transport). If a network ACL, host-based firewall (iptables, Windows Defender Firewall, cloud security group), or intermediate appliance blocks that port, the agent cannot reach the manager even when the service is running.
Cause 3: ossec.conf on the agent has the wrong manager address. Automated provisioning frequently introduces IP address typos, leaves a template placeholder (like MANAGER_IP), or points agents to a previous manager hostname. The agent service starts, but it connects to a nonexistent or wrong destination.
Cause 4: Time skew exceeds the tolerance threshold. Wazuh's enrollment process includes a timestamp check. If the system clock on the agent and the manager differ by more than the configured tolerance (default: 10 minutes in many deployments), the authd enrollment step or the connection handshake can fail. This shows up as Never Connected when the registration appeared to succeed because the key was written, but the subsequent connection check rejected the timestamp.
Cause 5: TLS certificate or keystore mismatch when using wazuh-authd with SSL verification. When authd is configured with ssl_verify_host: yes and the agent was enrolled with a certificate from a different CA chain than the manager expects, the SSL handshake during connection setup fails. The agent logs a certificate validation error at the connection attempt, not at enrollment time.
Diagnostics: Isolating the Root Cause
Run these checks in order. Each one takes under two minutes and rules out or confirms one of the five causes above.
Step 1: Confirm the agent service is running.
On Linux:
systemctl status wazuh-agent
On Windows (PowerShell):
Get-Service WazuhSvc
If the service is stopped, that is Cause 1. Skip the remaining steps and go straight to the fix for Cause 1.
Step 2: Check /var/ossec/etc/ossec.conf for the manager address.
grep -A5 '<server>' /var/ossec/etc/ossec.conf
Expected output:
<server>
<address>192.0.2.10</address>
<port>1514</port>
<protocol>tcp</protocol>
</server>
If <address> shows a placeholder string, a stale IP, or a hostname that does not resolve, that is Cause 3.
Step 3: Test port reachability from the agent.
On Linux:
nc -zv <manager-ip> 1514
On Windows (PowerShell):
Test-NetConnection -ComputerName <manager-ip> -Port 1514
A Connection refused error means the manager is reachable but nothing is listening on 1514 (check if wazuh-manager is running on the manager host). A timeout with no response means a firewall is dropping the packets: Cause 2.
Step 4: Read the agent-side connection log.
tail -50 /var/ossec/logs/ossec.log | grep -E 'ERROR|WARN|connect|invalid|clock'
Log lines to look for:
ERROR: (1210): Queue '/var/ossec/queue/sockets/queue' not accessibleor similar: Cause 1 (service not fully started).ERROR: (4101): resolving agent.conforfailed to connect: Cause 3 (manager address issue).WARN: (1403): OS time is NOT synchronized with the server: Cause 4 (clock skew).ERROR: SSL errororcertificate verify failed: Cause 5 (TLS mismatch).
Step 5: Check the manager-side agent list.
On the Wazuh manager:
/var/ossec/bin/agent_control -l | grep -i 'never'
If the agent appears in this list, the registration succeeded. If it does not appear at all, re-run enrollment rather than troubleshooting a connection problem.
Briefings like this, every morning before 9am.
Threat intel, active CVEs, and campaign alerts, distilled for practitioners. 50,000+ subscribers. No noise.
Fixes: Resolving Each Root Cause
Fix for Cause 1 (service not running or not restarted):
Start and enable the wazuh-agent service:
systemctl enable wazuh-agent
systemctl start wazuh-agent
For agents enrolled via script that need a restart after a key was already written:
systemctl restart wazuh-agent
Wait 30 seconds and check status:
systemctl status wazuh-agent
The agent should move from Never Connected to Active in the Wazuh console within one to two minutes of the service starting successfully.
Fix for Cause 2 (firewall blocking port 1514):
On the agent host (Linux, using iptables):
iptables -I OUTPUT -p tcp --dport 1514 -d <manager-ip> -j ACCEPT
iptables-save > /etc/iptables/rules.v4
For cloud environments (AWS security group, Azure NSG, GCP firewall rule): add an outbound rule allowing TCP 1514 from the agent subnet to the manager's private IP. If UDP transport is configured, open UDP 1514 instead.
After opening the port, restart the wazuh-agent service to force a new connection attempt.
Fix for Cause 3 (wrong manager address in ossec.conf):
Edit /var/ossec/etc/ossec.conf:
<client>
<server>
<address>192.0.2.10</address> <!-- replace with actual manager IP -->
<port>1514</port>
<protocol>tcp</protocol>
</server>
</client>
For large fleets, push the corrected ossec.conf via Ansible or your existing configuration management tool. After updating:
systemctl restart wazuh-agent
Fix for Cause 4 (clock skew):
Synchronize the agent's clock with an NTP server:
chronyc makestep
or
ntpdate -u pool.ntp.org
Verify sync:
chronyc tracking | grep 'System time'
If the offset is under 10 seconds, restart wazuh-agent. For persistent drift, configure chrony or ntpd to run as a service and set the same NTP source on both agent and manager.
Fix for Cause 5 (TLS/SSL certificate mismatch):
On the manager, verify the CA that signed the agent certificate matches what authd expects:
openssl verify -CAfile /var/ossec/etc/sslmanager.cert /path/to/agent.cert
If verification fails, re-enroll the agent using a certificate signed by the correct CA, or temporarily disable SSL verification in authd's configuration to confirm this is the cause, then re-enroll with the correct certificate chain before re-enabling verification.
Validating That the Agent Is Now Active
After applying the fix, do not rely on the Wazuh web console alone to confirm resolution. Check both sides of the connection.
On the manager:
/var/ossec/bin/agent_control -l | grep -i '<agent-name>'
The output line should show Active status and a recent last-contact timestamp. If it still shows Never Connected, the fix has not taken effect.
On the agent:
tail -20 /var/ossec/logs/ossec.log
Look for a line similar to:
INFO: (1210): Successfully connected to manager '192.0.2.10:1514'
If you see this line, the agent is communicating. Wait two to three minutes and check the Wazuh console: the agent should now appear as Active.
Confirm events are flowing:
On the agent, generate a test event that Wazuh is configured to detect. A failed sudo attempt works on most Linux systems:
sudo -u root false
On the manager, check that the event appeared:
grep -r '<agent-name>' /var/ossec/logs/alerts/alerts.log | tail -5
An alert entry within 60 seconds confirms end-to-end event flow, not just a TCP handshake.
Known Failure Cases After Applying the Fix
Agent restarts successfully but returns to Never Connected within seconds. This usually means the manager's IP is reachable but wazuh-manager is not accepting connections, often because wazuh-remoted is not running on the manager host. Check the manager's service status:
systemctl status wazuh-manager
If wazuh-manager is running but the agent still cannot connect, check whether the manager has a client.keys entry for this agent:
grep '<agent-name>' /var/ossec/etc/client.keys
A missing entry means the enrollment step did not complete on the manager side, even if the agent has a key locally. Re-run enrollment.
Mass-enrolled agents fix one by one but new deployments keep producing Never Connected. The provisioning script is not restarting wazuh-agent after writing ossec.conf. Add systemctl restart wazuh-agent to the end of the provisioning playbook, with a 30-second wait and a status check before the play completes.
Agent shows Active in the console but no events arrive. This is not a Never Connected problem. The agent connected but its ruleset or decoder is filtering all incoming events. Check the active rule set and confirm the log sources are being collected:
/var/ossec/bin/agent_control -i <agent-id>
This shows the agent's configuration summary, including which log files are monitored.
When to Escalate
Escalate to the Wazuh community forums or raise a GitHub issue when:
-
The agent log shows successful connection messages but the console never updates from Never Connected. This can indicate a UI rendering bug or a stale cache state in the Wazuh indexer. Clearing the agent's indexer document and re-enrolling usually resolves it, but it is worth confirming against the GitHub issue tracker before spending time on this.
-
Port 1514 is reachable, the agent service is running, ossec.conf is correct, and the clock is synchronized, but the connection still fails with a non-SSL error. Check whether the manager is running Wazuh 4.3 or later and the agent is on a version older than 4.0. The handshake protocol changed between major versions, and mixed-version environments where the agent is more than one major version behind the manager are not supported.
-
TLS errors persist after re-enrolling with a valid certificate. Collect the full SSL handshake trace from the agent log at debug level (set
<logformat>debug</logformat>temporarily in ossec.conf) and include it in the escalation. Certificate chain errors require the full trace to diagnose remotely.
When opening a GitHub issue, include: the Wazuh version on both agent and manager, the OS and kernel version on the agent host, the relevant section of the agent-side ossec.log (at minimum the last 50 lines after the most recent service restart), and the output of agent_control -l filtered to the affected agent.
The bottom line
Never Connected is not the same problem as Disconnected. The fix sequence is: confirm the service is running, verify the manager address in ossec.conf, test port 1514 reachability, read the agent-side ossec.log for the specific error, and apply the matching fix. Most Never Connected cases in fleet deployments come from provisioning scripts that write the key but forget to restart the service. Validate with both agent_control on the manager side and a generated test event on the agent side, not just the console status badge. For broader SIEM deployment context including Wazuh vs. Elastic Stack architecture decisions, see this open source SIEM build guide.
Frequently asked questions
What is the difference between Never Connected and Disconnected in the Wazuh console?
Never Connected means the agent registered successfully (its key is in client.keys) but has never established a working connection to the manager since registration. Disconnected means the agent was previously Active and communicating, then stopped. The two states require different diagnostics: Never Connected points to enrollment completion issues, service startup, firewall rules, or ossec.conf misconfiguration. Disconnected points to network interruptions, service crashes, or resource pressure on the agent host that occurred after the agent was already working.
Why does my Wazuh agent stay in Never Connected even after I restarted the service?
If restarting wazuh-agent does not change the status, the most common remaining causes are: the manager address in ossec.conf is wrong (typo or placeholder value from a provisioning template), port 1514 is blocked by a host-based firewall or network ACL, or the manager host's wazuh-remoted service is not running. Run the diagnostics in order: grep ossec.conf for the server address, test port 1514 with nc or Test-NetConnection, then read the last 50 lines of /var/ossec/logs/ossec.log for the specific error message that identifies the actual block.
How do I fix Wazuh agents enrolled by an Ansible playbook that all show Never Connected?
Mass enrollment via Ansible typically produces Never Connected agents when the playbook writes ossec.conf and registers the agent but does not restart the wazuh-agent service afterward. Add a handler or a task at the end of the role that runs `systemctl restart wazuh-agent`, followed by a `wait_for` check confirming the service is in running state before the play completes. This ensures the agent reads the new configuration and attempts a connection during provisioning rather than on first reboot.
What port does Wazuh use for agent-to-manager communication?
Wazuh agents communicate with the manager on TCP port 1514 by default. UDP 1514 is also supported and can be configured in the ossec.conf server block. The wazuh-authd enrollment service uses TCP port 1515, but that port is only needed during initial registration, not for ongoing agent-to-manager event communication. After enrollment, only port 1514 must remain open between the agent and manager for the agent to function.
How do I check if a Wazuh agent successfully enrolled on the manager side?
Run `/var/ossec/bin/agent_control -l` on the Wazuh manager host and look for the agent's name in the output. If the agent appears with Never Connected status, the registration key is present but no connection has been established. If the agent does not appear at all in the list, the enrollment step did not complete on the manager, and you need to re-run enrollment. This distinction matters because fixing a connection failure (agent present but Never Connected) requires different steps than completing a failed enrollment (agent absent from the list).
Can a Wazuh agent in Never Connected status still receive configuration updates from the manager?
No. Configuration distribution, rule updates, and all manager-to-agent communication require an active connection. An agent in Never Connected status cannot receive centralized ossec.conf updates, agent group assignments, or any other management operations that the manager pushes. This means that if you are trying to push a corrected ossec.conf to fix the Never Connected state itself, you cannot do it through the Wazuh management plane and must apply the fix directly on the agent host via your provisioning system, SSH, or WinRM.
Sources & references
Free resources
Critical CVE Reference Card 2025–2026
25 actively exploited vulnerabilities with CVSS scores, exploit status, and patch availability. Print it, pin it, share it with your SOC team.
Ransomware Incident Response Playbook
Step-by-step 24-hour IR checklist covering detection, containment, eradication, and recovery. Built for SOC teams, IR leads, and CISOs.
Daily briefings + Google Top Stories in one step.
Enter your email and we'll subscribe you to the daily briefing and add Decryption Digest to your Google Search feed at the same time.
Founder & Cybersecurity Evangelist, Decryption Digest
Cybersecurity professional with expertise in threat intelligence, vulnerability research, and enterprise security. Covers zero-days, ransomware, and nation-state operations for 50,000+ security professionals every morning.