Wazuh Agent Not Connecting to Manager? 12 Proven Fixes

How to Configure File Integrity Monitoring (FIM) in WazuhFew things are more frustrating than deploying a Wazuh agent only to discover that it never connects to the manager.

Whether the agent shows a Disconnected status, remains stuck in Pending, fails during enrollment, or never appears in the dashboard at all, a broken agent-manager connection leaves systems unmonitored and creates dangerous visibility gaps in your security operations.

How a Wazuh Agent Connnection Can Fail

A Wazuh agent connection failure can present itself in several ways:

• The agent appears as Disconnected in the Wazuh dashboard.
• The endpoint never shows up in the manager after installation.
• Agent registration or enrollment fails with authentication errors.
• The agent connects temporarily but repeatedly drops offline.
• Log files contain connection timeout, key mismatch, or enrollment errors.

According to the official Wazuh documentation, agents can exist in several connection states, including Active, Pending, Never Connected, and Disconnected.

An agent that remains in a non-active state typically indicates a communication, authentication, enrollment, or configuration problem that requires investigation.

This communication channel is critical because the Wazuh architecture depends on agents securely transmitting logs, security events, file integrity monitoring data, vulnerability information, and endpoint telemetry back to the manager for analysis.

If the connection fails, the manager loses visibility into the endpoint, reducing the effectiveness of threat detection, compliance monitoring, and incident response capabilities.

As the Wazuh team explains, agent enrollment and communication rely on secure authentication keys and encrypted communication between the agent and manager.

In real-world deployments, the root cause is often surprisingly simple.

Security practitioners frequently report issues such as blocked ports, incorrect manager IP addresses, duplicate agent names, firewall restrictions, authentication key mismatches, and DNS resolution problems.

Community troubleshooting discussions consistently show that networking and enrollment misconfigurations account for a large percentage of connection failures.

The good news is that most Wazuh agent connectivity problems can be resolved quickly once you follow a structured troubleshooting process.

What You Will Learn In This Guide

In this guide, we’ll walk through 12 proven fixes that actually work, starting with basic network connectivity checks and progressing to enrollment, authentication, firewall, and configuration troubleshooting.

By the end of this article, you’ll have a systematic process for diagnosing and resolving nearly every scenario where a Wazuh agent is not connecting to the manager.

Additional Resources:

Wazuh Agent Enrollment Troubleshooting

Wazuh Agent Connection Status Documentation

If you’re setting up a new endpoint and haven’t completed deployment yet, see our How to Install a Wazuh Agent on Windows Server guide.

How Wazuh Agent-to-Manager Communication Works

Before diving into specific fixes, it’s important to understand how communication between a Wazuh agent and manager actually works.

Understanding the connection architecture makes troubleshooting significantly easier because you’ll know exactly where failures can occur.

Understanding the Connection Architecture

Wazuh uses a centralized architecture in which endpoint agents collect security data and forward it to a central manager for processing, correlation, alerting, and storage.

Role of the Wazuh Agent

The Wazuh agent is installed on monitored endpoints such as Windows servers, Linux servers, workstations, and cloud instances.

Its responsibilities include:

• Collecting system logs
• Monitoring file integrity changes
• Detecting rootkits and malware indicators
• Gathering vulnerability assessment data
• Monitoring system configurations
• Forwarding security events to the manager

The agent acts as the primary data collection component of the Wazuh platform.

Role of the Wazuh Manager

The Wazuh manager serves as the central processing hub.

It is responsible for:

• Authenticating agents
• Receiving security events
• Applying detection rules
• Correlating events
• Generating alerts
• Managing agent configurations
• Forwarding data to the indexing and visualization layer

Without successful communication to the manager, the agent cannot contribute any security telemetry to the platform.

For a deeper comparison of Wazuh’s architecture versus traditional host-based intrusion detection systems, see our Wazuh vs OSSEC article.

Authentication and Enrollment Process

Before an agent can communicate with the manager, it must first be enrolled.

The enrollment process typically works as follows:

1. The agent contacts the manager.
2. The manager verifies the enrollment request.
3. Authentication keys are generated and exchanged.
4. The agent stores its assigned credentials.
5. Future communications use the established trust relationship.

According to the official Wazuh documentation, agent enrollment is a critical security step that prevents unauthorized systems from sending data to the manager.

If enrollment fails, the agent will never successfully connect.

Communication Ports Used by Wazuh

Several ports are commonly involved in Wazuh deployments:

A blocked enrollment port (1515) often prevents registration, while a blocked communication port (1514) can cause agents to appear disconnected after enrollment.

Always verify that these ports are allowed through firewalls, security groups, and network access control lists.

Typical Data Flow

Understanding the normal communication sequence can help identify exactly where the failure occurs.

Agent Starts

The Wazuh service starts on the endpoint and loads its configuration from the local agent configuration file.

Agent Authenticates

The agent attempts to authenticate using previously stored credentials or begins the enrollment process if it has not yet been registered.

Manager Validates the Agent

The manager checks the authentication key and verifies that the agent is authorized to communicate.

Secure Communication Channel Is Established

Once authentication succeeds, encrypted communication is established between the agent and manager.

Security Events Begin Flowing

The agent begins transmitting:

• Log events
• File integrity monitoring events
• Security alerts
• Inventory information
• Vulnerability assessment data

At this point, the agent should appear as Active in the Wazuh dashboard.

Common Reasons Agents Fail to Connect

Although Wazuh connectivity problems can seem complex, most failures fall into a handful of categories.

Network Connectivity Issues

The agent simply cannot reach the manager due to routing problems, VPN issues, subnet restrictions, or network outages.

Firewall Restrictions

One of the most common causes of connection failures is a firewall blocking ports 1514 or 1515.

Incorrect Manager IP Address

A surprisingly common mistake is entering the wrong manager IP address during installation or configuration.

Enrollment Problems

Authentication failures, duplicate agent IDs, or corrupted enrollment keys can prevent successful registration.

DNS Resolution Failures

If the agent uses a hostname instead of an IP address, DNS issues may prevent the manager from being located.

TLS or Certificate Errors

Encrypted communication can fail when certificates are invalid, expired, or improperly configured.

Version Incompatibilities

While Wazuh generally supports mixed-version environments, significant version differences between agents and managers can occasionally create communication issues.

For organizations evaluating alternative security monitoring platforms, our comparisons of Wazuh vs Splunk, Wazuh vs Graylog, and Wazuh vs OpenSearch explain how different architectures handle agent communication and event collection.

Fix #1: Verify Basic Network Connectivity

The first troubleshooting step is also the simplest: confirm that the agent can actually reach the manager over the network.

Many administrators immediately investigate certificates, enrollment keys, or Wazuh configurations only to discover later that basic network communication was never working.

Test Connectivity Between Agent and Manager

Start by testing connectivity from the agent machine.

Linux

ping <manager-ip>

Example:

ping 192.168.1.10

Windows

ping <manager-ip>

Example:

ping 192.168.1.10

If the manager responds successfully, you know that basic IP communication is functioning.

Verify the Manager Is Reachable

When reviewing the ping results, pay attention to more than just whether replies are received.

Check Packet Loss

Packet loss can cause intermittent disconnects even when communication appears functional.

Look for output similar to:

0% packet loss

Anything significantly above zero may indicate a network issue.

Check Latency

Excessive latency can create communication instability, especially across VPN connections or geographically distributed environments.

Monitor round-trip times and note any large spikes.

Confirm Routing Is Functioning Correctly

If connectivity appears inconsistent, run a traceroute to identify routing issues.

Linux:

traceroute <manager-ip>

Windows:

tracert <manager-ip>

This can reveal routing loops, unreachable hops, or VPN misconfigurations.

What to Do if Ping Fails

If the manager does not respond, focus on fixing the network path before moving to later troubleshooting steps.

Verify Network Routes

Confirm that the agent has a valid route to the manager’s subnet.

Linux:

ip route

Windows:

route print

Look for missing routes or incorrect gateways.

Check VPN Configurations

Many enterprise Wazuh deployments rely on VPN connectivity.

Verify:

• VPN tunnel status
• Route propagation
• Split-tunneling policies
• Network access rules

A disconnected or misconfigured VPN frequently causes agents to appear offline.

Inspect Cloud Security Groups

If your Wazuh manager is hosted in cloud infrastructure, verify that security groups and network ACLs allow traffic between the agent and manager.

Review inbound and outbound rules for:

• TCP 1514
• TCP 1515
• ICMP (for troubleshooting)

Many cloud deployments fail because the required Wazuh ports were never opened.

Once basic connectivity is confirmed, the next step is verifying that the required Wazuh ports are accessible and not being blocked by host-based or network firewalls.

Additional Resources

Wazuh Agent Enrollment Documentation

Wazuh Agent Connection States

Default Ports Reference

Fix #2: Confirm the Wazuh Manager Service Is Running

Even if network connectivity is working perfectly, agents cannot connect if the Wazuh manager itself is offline.

Before investigating enrollment keys, firewalls, or configuration files, verify that the manager service is running properly.

This is especially important after system updates, configuration changes, migrations, or unexpected server reboots.

Check Manager Status on Linux

On the Wazuh manager server, check the service status:

systemctl status wazuh-manager

A healthy service should display output indicating that the service is active (running).

Look for:

• Active status
• Recent startup timestamps
• No fatal errors
• No repeated restart attempts

If the service is inactive, failed, or stuck in a restarting state, agents will be unable to connect.

Restart the Manager

If the service appears unhealthy, restart it:

systemctl restart wazuh-manager

After restarting, verify the status again:

systemctl status wazuh-manager

In many cases, a restart resolves temporary issues caused by configuration reloads, memory pressure, or interrupted processes.

Review Service Logs

If the manager refuses to start or repeatedly crashes, inspect the logs.

Useful locations include:

/var/ossec/logs/ossec.log

And:

journalctl -u wazuh-manager

These logs typically provide more detailed error information than the systemctl output.

Signs the Service Failed to Start

Common indicators include:

• Service status shows failed
• Continuous restart loops
• Fatal initialization errors
• Missing configuration files
• Port binding failures
• Permission-related errors

Common Startup Errors

Some of the most frequently reported manager startup issues include:

Invalid Configuration Syntax

A malformed XML entry inside ossec.conf can prevent the manager from starting.

Port Already in Use

Another process may already be listening on required Wazuh ports.

You can check port usage with:

ss -tulpn | grep 1514

Corrupted Configuration Files

Configuration files modified manually may contain syntax errors or unsupported settings.

Resource Constraints

Low memory, exhausted disk space, or high CPU utilization can sometimes prevent successful startup.

According to the official Wazuh documentation, startup and operational issues are typically logged in ossec.log, making it the primary source for diagnosing manager-side failures.

Additional Resources

Wazuh Log Files Reference

Fix #3: Verify the Agent Service Is Running

A surprisingly common cause of agent connection problems is that the agent service is not actually running.

Installation may have completed successfully, but the service may have failed to start automatically or stopped due to an error.

Check Agent Status

Start by confirming the agent service is active.

Linux

systemctl status wazuh-agent

A healthy agent should display:

Active: active (running)

If the service shows inactive, failed, or dead, the manager will never receive data from that endpoint.

Windows

Open PowerShell as Administrator and run:

Get-Service Wazuh

You should see:

Status   Name    DisplayName
------   ----    -----------
Running  Wazuh   Wazuh Agent

If the status is Stopped, the service must be restarted.

Restart the Agent

Restarting the service often resolves temporary communication issues.

Linux

systemctl restart wazuh-agent

Windows

Restart-Service Wazuh

After restarting, wait approximately one minute and verify whether the agent appears as Active in the dashboard.

Check for Startup Errors

If the agent immediately stops again, review the logs.

Linux

tail -f /var/ossec/logs/ossec.log

Windows

Review:

C:\Program Files (x86)\ossec-agent\ossec.log

Common agent startup issues include:

• Invalid manager address
• Authentication key problems
• DNS failures
• Network connectivity issues
• Corrupted configuration files
• Permission problems

The log file will usually identify the exact reason the service failed.

If you’re troubleshooting a Windows deployment specifically, see our How to Install a Wazuh Agent on Windows Server guide for additional service management and troubleshooting tips.

Fix #4: Ensure the Correct Manager IP Address Is Configured

Even a perfectly functioning agent cannot connect if it is attempting to contact the wrong manager.

Incorrect IP addresses, outdated hostnames, and simple typing mistakes are among the most common causes of Wazuh connection failures.

Locate the Agent Configuration File

The manager address is defined within the agent’s ossec.conf file.

Linux

/var/ossec/etc/ossec.conf

Windows

C:\Program Files (x86)\ossec-agent\ossec.conf

Open the file using your preferred editor.

Verify the <address> Setting

Locate the server definition.

Example:

<client>
  <server>
    <address>192.168.1.100</address>
  </server>
</client>

Verify that the configured address matches the actual Wazuh manager IP address or hostname.

Common Configuration Mistakes

Wrong IP Address

The manager may have been moved, rebuilt, or assigned a new address.

Always verify the current server IP directly from the manager.

Old Manager Hostname

Organizations frequently migrate managers to new infrastructure but forget to update agent configurations.

Agents continue attempting to connect to a server that no longer exists.

Typographical Errors

A single missing digit or incorrect character can prevent communication entirely.

Examples:

<address>192.168.1.10</address>

instead of:

<address>192.168.1.100</address>

After making changes, restart the agent service so the new configuration is loaded.

If you’re evaluating centralized security monitoring architectures, our Wazuh vs Splunk and Wazuh vs Graylog comparisons explain how different platforms handle agent communications and centralized event collection.

Fix #5: Check That Required Ports Are Open

Wazuh relies on specific network ports for enrollment and ongoing communication.

Even if the agent can ping the manager, blocked ports can still prevent successful registration and data transfer.

Default Wazuh Ports

If either of these ports is blocked, agents may appear disconnected, stuck in enrollment, or unable to transmit events.

Test Port Accessibility

After confirming network connectivity, verify that the required ports are reachable.

Linux

Test communication port 1514:

nc -zv <manager-ip> 1514

Test enrollment port 1515:

nc -zv <manager-ip> 1515

Successful output should indicate that the connection was established.

Windows

PowerShell provides a built-in connectivity test:

Test-NetConnection <manager-ip> -Port 1514

For enrollment testing:

Test-NetConnection <manager-ip> -Port 1515

Look for:

TcpTestSucceeded : True

What Closed Ports Usually Indicate

If connectivity tests fail, the problem is usually one of the following.

Firewall Blocks

Host-based firewalls may be blocking inbound or outbound Wazuh traffic.

Examples include:

• Windows Defender Firewall
• firewalld
• UFW
• iptables

Security Group Restrictions

Cloud environments often use security groups that explicitly control allowed traffic.

Verify rules in:

• AWS Security Groups
• Azure Network Security Groups
• Google Cloud Firewall Rules

Network ACL Rules

Some environments enforce additional network filtering through ACLs that can block traffic even when security groups permit it.

Verify the Manager Is Listening

You should also confirm that the manager is actively listening on the required ports.

ss -tulpn | grep 151

Expected output should show listeners on ports 1514 and 1515.

If the ports are not listening, revisit Fix #2 and investigate the manager service status and logs.

Additional Resources

Wazuh Architecture and Default Ports Documentation

Wazuh Agent Enrollment Documentation

Fix #6: Review Firewall Rules on Both Systems

After verifying that the correct ports are open, the next step is determining whether a firewall is silently blocking Wazuh traffic.

Firewalls are among the most common causes of agent-manager communication failures, particularly in enterprise environments where multiple layers of network security may be involved.

Remember that Wazuh traffic must be permitted on both sides of the connection:

• The agent must be allowed to send traffic.
• The manager must be allowed to receive traffic.
• Intermediate firewalls must allow traffic to pass through.

Linux Firewall Checks

Most Linux systems use either UFW or Firewalld.

UFW

Check the current firewall configuration:

ufw status

Look for rules that allow traffic on:

• TCP 1514
• UDP 1514 (if applicable)
• TCP 1515

Example:

1514/tcp ALLOW Anywhere
1515/tcp ALLOW Anywhere

If the ports are missing, add them:

ufw allow 1514/tcp
ufw allow 1515/tcp

Firewalld

For systems running Firewalld:

firewall-cmd --list-all

To verify specific ports:

firewall-cmd --list-ports

If necessary, allow the ports:

firewall-cmd --permanent --add-port=1514/tcp
firewall-cmd --permanent --add-port=1515/tcp
firewall-cmd --reload

Windows Firewall Checks

Windows Defender Firewall can block Wazuh communications even when network connectivity appears normal.

Open:

Windows Defender Firewall with Advanced Security

Review both inbound and outbound rules.

Inbound Rules

Ensure the manager can receive:

• TCP 1514
• TCP 1515

Outbound Rules

Ensure the agent can initiate connections to the manager.

Many organizations focus only on inbound filtering and overlook outbound restrictions.

Security Software Conflicts

Endpoint security tools can occasionally interfere with Wazuh communications.

Examples include:

• Endpoint Detection and Response (EDR) platforms
• Host Intrusion Prevention Systems (HIPS)
• Antivirus products
• Application control solutions

Temporary testing with security software disabled (where organizational policy permits) can help determine whether these products are interfering with communications.

If you’re comparing Wazuh against commercial endpoint security platforms, see our Wazuh vs SentinelOne and Wazuh vs CrowdStrike comparisons.

Recommended Wazuh Firewall Exceptions

At a minimum, allow:

After updating firewall rules, restart the affected services and test connectivity again.

Fix #7: Verify Agent Enrollment Was Successful

Many administrators assume that installation automatically means enrollment succeeded.

In reality, an agent can be installed and running while remaining completely unregistered with the manager.

If enrollment fails, the manager will reject communication attempts from the agent.

Check Agent Registration Status

The manager maintains a list of enrolled agents.

If the affected endpoint is missing from this list, enrollment likely failed.

List Registered Agents

On the manager server, launch the agent management utility:

/var/ossec/bin/manage_agents

Choose the option to list existing agents.

You should see the endpoint listed along with:

• Agent ID
• Agent name
• Assigned IP address

Signs Enrollment Failed

Several indicators suggest the agent never successfully enrolled.

Agent Not Listed

If the endpoint does not appear in the registered agent list, enrollment did not complete successfully.

Duplicate Entries

Sometimes administrators reinstall agents without removing old registrations.

This can create duplicate entries that confuse authentication.

For example:

webserver01
webserver01-old
webserver01-test

Multiple registrations for the same system can lead to key conflicts.

Invalid Keys

Authentication keys must match between the manager and agent.

If keys become corrupted or mismatched, the manager will reject connection attempts.

Common log messages include:

Invalid key

or

Agent authentication failed

Re-Enroll the Agent

If enrollment appears broken, re-registering the agent is often the fastest solution.

Step 1: Remove the Existing Agent Entry

From the manager:

/var/ossec/bin/manage_agents

Delete the problematic agent entry.

Step 2: Remove Existing Agent Credentials

On the endpoint, remove the existing authentication information.

The exact process varies by operating system and Wazuh version.

Step 3: Re-Register the Agent

Register the endpoint again using:

/var/ossec/bin/agent-auth -m <manager-ip>

Or follow the enrollment method used in your environment.

Step 4: Restart the Agent

systemctl restart wazuh-agent

or

Restart-Service Wazuh

Step 5: Verify Successful Registration

Return to the dashboard and confirm that the endpoint appears as Active.

According to Wazuh documentation, enrollment and authentication issues are among the most common causes of agents remaining disconnected after installation.

Additional Resources

Wazuh Agent Enrollment Guide

Fix #8: Inspect Agent and Manager Logs for Errors

When basic troubleshooting fails, logs almost always reveal the root cause.

Both the agent and manager maintain detailed logs that record connection attempts, authentication failures, routing problems, and configuration issues.

Agent Logs

Begin by examining the endpoint logs.

Linux

tail -f /var/ossec/logs/ossec.log

Attempt to restart the agent while monitoring the log output.

Windows

Review:

C:\Program Files (x86)\ossec-agent\ossec.log

Look for recent connection-related messages.

Manager Logs

The manager records communication events from all enrolled agents.

Monitor the manager log:

tail -f /var/ossec/logs/ossec.log

Then attempt to reconnect the agent.

Any authentication, enrollment, or connectivity errors should appear immediately.

Common Error Messages and Their Meaning

Additional Log Messages Worth Investigating

Agent Not Found

Typically indicates the endpoint is attempting to authenticate using an unknown registration.

Duplicate Agent Name

The manager has multiple records for the same endpoint.

Connection Timeout

Traffic is being blocked or dropped somewhere in the network path.

Hostname Resolution Failure

DNS is unable to resolve the configured manager hostname.

Security engineers frequently note that reviewing logs first can eliminate hours of unnecessary troubleshooting because the exact failure is often recorded explicitly.

Additional Resources

Wazuh Server Logs Documentation

Fix #9: Resolve DNS and Hostname Resolution Problems

Many Wazuh deployments use hostnames rather than IP addresses for manager communication.

While this improves flexibility, it also introduces DNS as another potential point of failure.

If DNS resolution breaks, agents may be unable to locate the manager even though the server itself is functioning correctly.

Test DNS Resolution

Verify that the hostname configured in ossec.conf resolves properly.

Linux

nslookup manager.example.com

Expected output should return the manager’s IP address.

You can also test:

host manager.example.com

or

dig manager.example.com

Windows

Resolve-DnsName manager.example.com

Successful output should contain the correct IP address.

Use IP Address Instead of Hostname

To quickly determine whether DNS is causing the issue, temporarily replace the hostname with the manager’s IP address.

Example:

<client>
  <server>
    <address>192.168.1.100</address>
  </server>
</client>

Restart the agent afterward.

If communication immediately succeeds, DNS is almost certainly the problem.

Verify Internal DNS Records

Check that:

• A records exist for the manager
• DNS zones are replicated correctly
• Internal DNS servers are reachable
• Hostnames resolve to the correct IP address
• No stale records remain after migrations

DNS issues frequently occur after:

• Server migrations
• Cloud migrations
• IP address changes
• Domain controller failures
• DNS cache corruption

Flush DNS Cache

If DNS records were recently updated, clear cached entries.

Linux

resolvectl flush-caches

Windows

ipconfig /flushdns

Then test resolution again.

If you’re running a large security monitoring deployment and evaluating alternative architectures, our Wazuh vs OpenSearch, and Security Onion vs Wazuh articles explore how different platforms handle centralized logging, agent communications, and infrastructure scalability.

Fix #10: Remove Duplicate or Corrupted Agent Entries

Duplicate agent records are a surprisingly common cause of Wazuh authentication failures, especially in environments where servers are frequently rebuilt, cloned, restored from snapshots, or reinstalled.

When multiple agent records exist for the same endpoint, the manager may receive authentication requests that do not match the expected enrollment keys, causing connection failures even when network communication is functioning correctly.

Identify Duplicate Agents

Begin by reviewing the list of registered agents on the manager.

Launch the agent management utility:

/var/ossec/bin/manage_agents

Select the option to list agents.

Look for:

• Multiple entries with the same hostname
• Old versions of the same server
• Decommissioned systems
• Agents with outdated IP addresses
• Duplicate agent IDs

Example:

001 webserver01
002 webserver01
003 webserver01-backup

In this scenario, the manager may not know which enrollment key should be associated with the active endpoint.

Delete the Old Agent Record

After identifying stale or duplicate registrations, remove them from the manager.

Using manage_agents:

/var/ossec/bin/manage_agents

Choose:

Remove an agent

Select the obsolete entry and confirm deletion.

Be careful not to remove the active production record unless you intend to re-enroll the endpoint.

Generate a New Enrollment Key

If the registration appears corrupted, generate a fresh authentication key.

From the manager:

/var/ossec/bin/manage_agents

Choose:

Extract key for an agent

Copy the newly generated key.

This creates a clean trust relationship between the agent and manager.

Reconnect the Agent

Import the new key on the endpoint and restart the agent service.

Linux:

systemctl restart wazuh-agent

Windows:

Restart-Service Wazuh

Then verify that the endpoint appears as Active in the Wazuh dashboard.

Why Duplicate Entries Cause Authentication Failures

Every enrolled agent is associated with:

• A unique agent ID
• A unique authentication key
• A unique registration record

When duplicate records exist, the manager may reject the agent because the presented credentials do not match the expected registration.

Common situations that create duplicates include:

• VM cloning
• Server rebuilds
• Agent reinstalls
• Disaster recovery restores
• Endpoint migrations

Many administrators spend hours troubleshooting networking and firewall settings only to discover that the actual problem is an outdated agent record left behind from a previous installation.

For environments that frequently rebuild infrastructure, proper agent lifecycle management is just as important as network configuration.

Fix #11: Check for TLS and Certificate Issues

If networking, enrollment, firewall rules, and agent registrations all appear correct, the next area to investigate is encrypted communication.

Modern Wazuh deployments rely heavily on secure communication channels.

Problems involving TLS certificates can prevent agents from establishing trusted connections to the manager.

Common TLS Problems

Certificate-related issues typically generate authentication or handshake errors within the logs.

The most common causes include:

Expired Certificates

Certificates have a defined validity period.

When a certificate expires, communication may be rejected automatically.

Check certificate expiration dates regularly, especially in long-running deployments.

Incorrect Certificates

A certificate generated for one server may accidentally be deployed to another.

Certificate subject names and hostnames must match the intended deployment.

Certificate Trust Issues

The agent must trust the certificate presented by the manager.

Trust failures commonly occur after:

• Certificate replacement
• Manager migration
• PKI changes
• Certificate authority updates

Validate Certificate Configuration

Review the relevant TLS settings in your Wazuh configuration files.

Verify:

• Correct certificate paths
• Correct private key paths
• Correct certificate authority files
• Appropriate file permissions

Also confirm that referenced certificate files actually exist.

Missing certificate files are a frequent source of startup and authentication failures.

Review Authentication Logs

The most useful information usually appears in the logs.

Monitor:

Agent Logs

tail -f /var/ossec/logs/ossec.log

Manager Logs

tail -f /var/ossec/logs/ossec.log

Look for messages such as:

SSL handshake failed

Certificate validation error

Unable to verify certificate

These messages generally point directly to the root cause.

Recreate Certificates if Necessary

If certificates appear corrupted, expired, or incorrectly configured, recreating them is often faster than attempting manual repairs.

A typical process includes:

1. Generate new certificates.
2. Replace existing certificate files.
3. Update configuration references if necessary.
4. Restart Wazuh services.
5. Verify successful authentication.

Organizations using automated certificate management systems should also verify that certificate renewals completed successfully.

According to guidance from the cybersecurity community and public key infrastructure best practices published by organizations such as the National Institute of Standards and Technology (NIST), certificate lifecycle management is one of the most common operational challenges affecting secure service-to-service communication.

For more information, you can view the NIST TLS Guidelines 

Fix #12: Verify Version Compatibility Between Agent and Manager

Although Wazuh generally supports communication between nearby versions, significant version differences can occasionally create enrollment, authentication, and communication problems.

Version compatibility should always be verified when agents suddenly stop connecting after an upgrade.

Supported Version Combinations

As a general best practice:

• Keep agents and managers on the same major version whenever possible.
• Upgrade managers before upgrading agents.
• Avoid running very old agents against significantly newer managers.
• Follow the compatibility guidance provided in the official Wazuh release documentation.

While minor version differences are often supported, large version gaps can introduce unexpected behavior.

How Version Mismatches Affect Connectivity

Version mismatches can cause:

• Enrollment failures
• Authentication issues
• Unsupported protocol errors
• Configuration parsing problems
• Missing feature compatibility

Symptoms may include:

Authentication failed

Unsupported version

or repeated connection attempts that never complete successfully.

Check Installed Versions

Verify the installed version on both systems.

Agent

Run:

wazuh-control info

Typical output:

WAZUH_VERSION="4.x.x"

Manager

Run:

/var/ossec/bin/wazuh-control info

Compare the reported versions.

Upgrade Outdated Components

If a significant version gap exists, upgrade the outdated component.

A recommended upgrade approach is:

1. Back up configurations.
2. Upgrade the manager.
3. Verify manager functionality.
4. Upgrade agents.
5. Confirm successful reconnection.

After upgrades, restart the affected services and verify agent status from the dashboard.

Organizations evaluating alternative security platforms often compare upgrade complexity and compatibility requirements.

Our Wazuh vs OpenEDR, Wazuh vs OSSIM, and Wazuh vs AlienVault comparisons discuss how different platforms handle upgrades, agent management, and version interoperability.

Version Compatibility Best Practices

To minimize future connectivity issues:

• Standardize on a supported Wazuh release.
• Maintain an upgrade schedule.
• Test upgrades in a staging environment first.
• Keep deployment documentation current.
• Review release notes before major upgrades.

Following these practices significantly reduces the likelihood of agent-manager communication failures caused by software version mismatches.

Wazuh Release Notes: https://documentation.wazuh.com/current/release-notes/index.html

Wazuh Upgrade Guide: https://documentation.wazuh.com/current/upgrade-guide/index.html

Advanced Troubleshooting Techniques

If you’ve worked through the previous fixes and your Wazuh agent still isn’t connecting to the manager, it’s time to move beyond basic troubleshooting and gather deeper diagnostic information.

The following techniques can help uncover issues involving packet loss, firewall interference, TLS negotiation failures, load balancers, cloud networking, and other complex connectivity problems.

Capture Network Traffic

Packet captures allow you to see exactly what is happening between the agent and manager.

This is often the fastest way to determine whether:

• Traffic is reaching the manager
• Responses are being returned
• Firewalls are dropping packets
• TLS handshakes are failing
• Network devices are interfering with communication

Using tcpdump

On Linux, use tcpdump to capture Wazuh traffic.

Monitor agent communication traffic:

tcpdump -i any port 1514

Monitor enrollment traffic:

tcpdump -i any port 1515

If packets appear on the agent but never reach the manager, a network device is likely blocking or dropping traffic.

You can also save captures for later analysis:

tcpdump -i any port 1514 -w wazuh-traffic.pcap

Using Wireshark

For more detailed analysis, open the capture file in Wireshark.

Wireshark allows you to:

• Inspect TCP conversations
• Review TLS negotiations
• Identify resets and retransmissions
• Detect malformed packets
• Analyze latency

Filtering Wazuh Traffic

Useful Wireshark filters include:

tcp.port == 1514

tcp.port == 1515

ip.addr == <manager-ip>

These filters isolate Wazuh-related traffic and make troubleshooting easier.

Identifying Dropped Packets

Watch for:

• TCP retransmissions
• TCP resets (RST)
• Incomplete handshakes
• One-way communication
• Unexpected connection terminations

These symptoms often indicate:

• Firewall filtering
• Security appliance interference
• Routing issues
• Network congestion

Enable Debug Logging

Debug logging provides significantly more information than standard logs.

Only enable it during troubleshooting because it can generate large log files.

Increase Agent Log Verbosity

Modify the agent configuration to increase logging levels.

After enabling debug mode, restart the service:

systemctl restart wazuh-agent

or

Restart-Service Wazuh

Analyze Debug Output

Debug logs often reveal:

• Authentication failures
• Key mismatches
• DNS issues
• TLS errors
• Network timeouts
• Protocol negotiation failures

Look for repeated error patterns rather than isolated messages.

Repeated failures generally indicate the true root cause.

When to Disable Debug Mode

After troubleshooting is complete:

• Return logging to normal levels
• Restart the service
• Verify connectivity remains stable

Leaving debug mode enabled permanently can increase disk usage and make routine log analysis more difficult.

Troubleshooting Wazuh Agents in Cloud Environments

Cloud deployments introduce additional networking layers that can affect agent-manager communication.

AWS Security Groups

In AWS, verify that security groups allow:

• TCP 1514
• TCP 1515

Both inbound and outbound rules should be reviewed.

Also check:

• VPC route tables
• Network ACLs
• Transit Gateway configurations
• VPN attachments

Azure Network Security Groups

For Azure deployments, confirm that:

• Network Security Groups permit Wazuh traffic
• Subnet-level rules allow communication
• Virtual network peering is configured correctly

A common issue occurs when subnet-level policies override VM-level access rules.

Google Cloud Firewall Rules

Google Cloud environments require firewall rules that explicitly permit Wazuh traffic.

Verify:

• Ingress rules
• Egress rules
• VPC routing
• Private service connectivity

Load Balancers and NAT Considerations

Some organizations place Wazuh managers behind load balancers or NAT devices.

Potential issues include:

• Session persistence problems
• Source IP translation
• Connection timeouts
• Idle session expiration

Whenever possible, test communication directly against the manager to eliminate intermediary devices as a variable.

Preventing Future Connection Problems

Fixing a disconnected agent is important. Preventing future outages is even better.

Organizations with mature Wazuh deployments typically establish operational processes that minimize connectivity issues before they occur.

Standardize Agent Deployment Procedures

Create a documented deployment process that includes:

• Installation steps
• Enrollment procedures
• Firewall requirements
• Verification checks
• Troubleshooting guidance

Standardization reduces configuration drift and human error.

Use DNS Instead of Hardcoded IPs

Whenever possible, configure agents to connect using a hostname instead of a static IP address.

Benefits include:

• Easier manager migrations
• Reduced reconfiguration effort
• Faster disaster recovery
• Simplified infrastructure changes

Just ensure that DNS availability is monitored properly.

Monitor Agent Health Regularly

Do not wait until an incident occurs to discover agents are offline.

Implement regular monitoring for:

• Agent status
• Last keepalive timestamps
• Enrollment failures
• Connection errors

This allows issues to be detected before visibility is lost.

Keep Wazuh Components Updated

Running supported versions helps prevent:

• Compatibility issues
• Authentication bugs
• Security vulnerabilities
• Protocol inconsistencies

Before upgrading, review release notes and test changes in a staging environment.

Document Enrollment and Key Management Processes

Many connectivity problems originate from poor key management.

Maintain clear documentation covering:

• Agent enrollment procedures
• Key rotation processes
• Certificate management
• Agent decommissioning
• Re-registration procedures

Organizations that document these processes typically experience far fewer authentication-related outages.

Frequently Asked Questions

Question: Why does my Wazuh agent show as disconnected?

A disconnected agent typically indicates one of the following:

• Network connectivity issues
• Firewall restrictions
• Manager service failures
• Invalid enrollment keys
• DNS problems
• TLS certificate issues

Review the agent and manager logs first, as they often reveal the exact cause.

Question: What ports must be open between the agent and manager?

The most important ports are:

Depending on your deployment architecture, additional ports may also be required.

Question: Can a firewall block Wazuh communication even if ping works?

Yes.

Ping uses ICMP, while Wazuh uses TCP and UDP.

It’s very common for ICMP traffic to succeed while ports 1514 and 1515 remain blocked.

Always perform port-specific testing using:

nc -zv <manager-ip> 1514

or

Test-NetConnection <manager-ip> -Port 1514

Question: How do I re-register a Wazuh agent?

A typical re-registration process involves:

1. Removing the existing agent record.
2. Generating a new enrollment key.
3. Re-enrolling the endpoint.
4. Restarting the agent service.
5. Verifying the connection in the dashboard.

Question: How can I tell if a Wazuh enrollment key is invalid?

Common indicators include:

• Authentication failures
• “Invalid key” log messages
• Enrollment failures
• Immediate disconnects after registration

Manager and agent logs usually provide clear evidence when keys do not match.

Question: Does a version mismatch prevent agent connections?

Sometimes.

Minor version differences are usually supported, but major version gaps can create:

• Authentication issues
• Enrollment failures
• Protocol incompatibilities

Keeping agents and managers on the same major release is considered best practice.

Question: How do I reconnect a Wazuh agent after changing the manager IP?

Update the manager address in the agent’s ossec.conf file:

<client>
  <server>
    <address>NEW_MANAGER_IP</address>
  </server>
</client>

Then restart the agent service and verify connectivity.

If DNS is being used, updating the DNS record may eliminate the need to modify every endpoint individually.

Conclusion

A Wazuh agent that refuses to connect to its manager can seem difficult to diagnose at first, but most connection failures ultimately stem from a relatively small set of underlying causes.

Recap of the 12 Proven Fixes

Throughout this guide, we’ve covered the most effective solutions for resolving a Wazuh agent not connecting to manager problem:

1. Verify network connectivity.
2. Confirm the manager service is running.
3. Verify the agent service is running.
4. Validate the manager configuration.
5. Check required ports.
6. Review firewall rules.
7. Verify successful enrollment.
8. Analyze agent and manager logs.
9. Resolve DNS issues.
10. Remove duplicate agent entries.
11. Validate TLS and certificates.
12. Verify version compatibility.

Recommended Troubleshooting Order

For the fastest diagnosis, follow this sequence:

1.Verify network connectivity

2. Confirm the manager is running

3. Confirm the agent is running

4.Verify manager address configuration

5. Test ports 1514 and 1515

6. Review firewall rules

7. Verify enrollment status

8. Analyze logs

9. Check DNS

10. Remove duplicate registrations

11. Investigate TLS issues

12. Verify version compatibility

Following this order helps eliminate the most common causes first and prevents wasted effort troubleshooting more advanced scenarios unnecessarily.

Quick Troubleshooting Checklist

Use this checklist whenever an agent appears disconnected:

• Can the agent reach the manager?
• Is the manager service running?
• Is the agent service running?
• Is the manager IP correct?
• Are ports 1514 and 1515 open?
• Are firewalls permitting traffic?
• Is the agent properly enrolled?
• Do the logs show errors?
• Is DNS functioning correctly?
• Are duplicate agent records present?
• Are certificates valid?
• Are versions compatible?

Working through these questions systematically will resolve the vast majority of connectivity problems.

Next Steps

Once connectivity has been restored:

• Confirm that security events are arriving at the manager.
• Verify that the agent status remains Active.
• Configure ongoing health monitoring.
• Implement automated deployment and enrollment processes.
• Document troubleshooting procedures for future incidents.

For deeper Wazuh administration guidance, you may also find these resources helpful:

How to Install a Wazuh Agent on Windows Server

How to Create Custom Detection Rules in Wazuh (With Examples)

Wazuh vs OSSEC

How to Configure File Integrity Monitoring (FIM) in Wazuh

Wazuh vs Splunk

By combining proactive monitoring, standardized deployment procedures, and the troubleshooting techniques covered in this guide, you’ll be able to keep your Wazuh agents reliably connected and your security visibility intact.