Duty analyst on shift

UK Cyber Defence

Wazuh consulting · Guide · Troubleshooting

Wazuh troubleshooting:the problems wesee most often.

When Wazuh stops working it usually fails in one of a handful of ways: agents that never connect or drop off, an indexer that turns yellow or red, disks that fill and block writes, a dashboard that is never ready, or alerts that quietly stop arriving. This guide takes each in turn, with the checks and commands we use ourselves, in the order we use them.

Wazuh 4.14Commands includedUpdated November 2026From a SOC that runs it

01The short answer

Check in this order: services, logs, disk, indexer health, then the network between agents and manager.

Most Wazuh outages we are called to have one of four causes: a full disk, a certificate or password changed in one place and not another, a load balancer sending traffic to the wrong node, or components on mismatched versions after an upgrade. The checks below find each of them in minutes. Run them before you restart anything, because a restart can hide the evidence.

First look
Service status and ossec.log on the manager
Most common cause
A full disk on the indexer
Most missed
Components on different versions after an upgrade
When to stop
Before deleting indices you cannot rebuild

Start here

The first five minutes

On the server, check that every central component is running and look for errors in its log:

sudo systemctl status wazuh-manager wazuh-indexer wazuh-dashboard filebeat
sudo grep -iE "error|critical|warn" /var/ossec/logs/ossec.log | tail -50
df -h

Then ask the indexer how it is:

curl -k -u admin https://localhost:9200/_cluster/health?pretty

Green means every shard is allocated. Yellow means some replica shards are not; red means a primary shard is missing and some data cannot be searched. On a single-node deployment, Wazuh's own indices expand their replicas automatically, so Wazuh's troubleshooting guidance says a healthy single node should report green, not yellow.

Finally, confirm the versions. All central components must run the same version, down to the patch number, and the manager must be the same version as its agents or newer. A mismatch after a partial upgrade causes many of the problems below.

Agents

Agents that never connected, disconnected or are pending

Wazuh shows each agent as active, disconnected, pending or never connected. Pending means the agent has connected and is waiting for the manager to acknowledge it; disconnected means no acknowledgement has arrived for 60 seconds or the connection was lost. Never connected means the agent enrolled but has never reported.

List them on the manager, and read the agent's own view of its state:

sudo /var/ossec/bin/agent_control -l
sudo grep ^status /var/ossec/var/run/wazuh-agentd.state

On Windows, the state file is C:\Program Files (x86)\ossec-agent\wazuh-agent.state and the log is ossec.log in the same folder. On macOS, look under /Library/Ossec/.

Check the network from the agent. Agents connect out to the manager on TCP 1514 and enrol on TCP 1515. From Linux, nc -zv <manager> 1514; from Windows, Test-NetConnection <manager> -Port 1514. A firewall in between, a proxy, or a manager address that resolves differently inside and outside the office are the usual causes.

Check the load balancer. In a cluster, enrolment on 1515 must reach the master node, which issues the keys, while event traffic on 1514 is balanced across workers. A balancer that sends 1515 to workers produces agents that enrol and then never connect, and at scale an enrolment storm as thousands retry at once. Wazuh's mailing list gives the same first advice for never-connected agents behind a balancer: check its configuration and its logs.

Check the keys and the name. The agent and the manager must hold matching entries in client.keys; if they differ, the agent cannot authenticate. Each agent also needs a unique name, which defaults to the hostname, so cloned machines and reused hostnames collide. Remove the stale entry on the manager and enrol again.

Check the version. An agent newer than its manager is not supported. Upgrade the manager first.

Enrolment

Enrolment errors

Read the agent's ossec.log and the manager's ossec.log side by side when an agent will not enrol. The causes we see most:

Symptom in the logsUsual causeFix
Cannot connect to the enrolment servicePort 1515 blocked, or the balancer sends it to a workerOpen 1515 to the master only
Invalid passwordThe enrolment password differs, or authd.pass cannot be readCheck the password and the file's owner and permissions
Duplicate or invalid agent nameTwo machines share a hostname, or an old entry remainsRemove the old agent or set a unique name at install
Enrols, then never connectsPort 1514 blocked, or the manager address differsTest 1514 from the agent and check the address in its configuration

Our installation guide shows how to set enrolment up securely in the first place, with a password and deployment variables.

Indexer

A yellow or red indexer, and unassigned shards

Find the shards that are not assigned, then ask the cluster why:

GET _cat/shards/wazuh-*?v&h=index,shard,prirep,state,unassigned.reason
GET _cluster/allocation/explain

The explanation usually names one of a few causes. Disk watermarks stop shards being placed on a node that is too full. Too many shards for the cluster's limit stop new daily indices being created. A missing node leaves its shards with nowhere to go. A lifecycle policy that moves older indices between hot and warm nodes can leave their replicas unassigned if the warm tier cannot hold them.

Fix the cause rather than forcing allocation. In particular, do not delete indices to make a cluster green until you know what they hold and whether you are required to keep it.

Disk

Disk full: when the indexer stops accepting data

OpenSearch, which the Wazuh indexer is built on, inherits Elasticsearch's disk watermarks. By default it stops placing new shards on a node at 85% disk use, starts moving shards away at 90%, and at 95%, the flood stage, makes every index on that node read-only. Alerts stop being stored, and the dashboard may stop letting anyone log in because its own indices are blocked too. The error reads like this:

blocked by: [TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark, index has read-only-allow-delete block]

To recover: free space first, by adding disk or deleting indices you have agreed you no longer need. Newer versions lift the block automatically once usage falls below the high watermark; if it remains, clear it:

PUT */_settings?expand_wildcards=all
{ "index.blocks.read_only_allow_delete": null }

Then stop it happening again. Set an index lifecycle policy so old indices are deleted on the schedule you decided, size the disk for your retention, and alert on disk use well before 85%. Raising the watermarks only moves the cliff.

Dashboard

Wazuh dashboard server is not ready yet

This message means the browser reached the dashboard, but the dashboard cannot reach the indexer. It is normal for a minute or two after the dashboard starts. If it persists:

  1. Check the indexer is running and healthy, using the commands above. A full disk or a red cluster is the most common cause.
  2. Read the dashboard's own log: sudo journalctl -u wazuh-dashboard | grep -iE "error|warn".
  3. If passwords were changed recently, check the dashboard still holds the right one for its indexer account. A password changed in the indexer but not in the dashboard's keystore produces exactly this message.
  4. Check the indexer addresses and certificate paths in /etc/wazuh-dashboard/opensearch_dashboards.yml.
  5. After an upgrade, check all three components are on the same version.

If the dashboard loads but says the Wazuh API is unreachable, the problem is between the dashboard and the manager instead: check the manager is running, that port 55000 is reachable from the dashboard, and the API credentials the dashboard uses.

Missing alerts

Agents are active but alerts have stopped

Follow an event from the agent to the screen and find where it stops.

Is the manager producing alerts? sudo tail -f /var/ossec/logs/alerts/alerts.json should show new lines. If it does not, the manager is not receiving events or no rule is matching them.

Is the alert reaching the indexer? In a standard deployment, Filebeat on the manager ships alerts to the indexer. sudo filebeat test output checks the connection. A changed password or certificate is the usual cause of failure.

Is the rule doing what you think? Paste a real log line into sudo /var/ossec/bin/wazuh-logtest to see which decoder and rule match, and at what level.

Did a rule change stop the engine? A custom rule that does not load can stop analysis entirely. Check ossec.log after any rule change, and test the configuration before restarting the manager.

Is the clock right? Events with the wrong time land in the wrong place in the dashboard and seem missing. Check time synchronisation on agents and servers.

If you run Wazuh with Graylog in place of the indexer, the second check becomes the shipper and the Graylog journal instead of Filebeat.

Upgrades

Problems after an upgrade

Upgrade the indexer first, then the manager, then the dashboard, then the agents, and keep the central components on identical versions. Most post-upgrade faults we see come from doing them in a different order, upgrading one node of a cluster and not the others, or letting the operating system's routine updates upgrade one Wazuh package on its own, which is why Wazuh recommends disabling its repository between planned upgrades.

Wazuh 5.0 is a different matter: it is a migration to a new deployment, not an upgrade, and its documentation says an in-place upgrade from 4.x is not supported. A readiness review sizes the work.

When to call for help

When it is time to stop and call someone

01

Data you must keep is at risk

Red clusters, read-only indices and deleting data to free space: decide with someone who has done it before.

02

It has happened before

The same fault twice means a cause nobody has found. A health check finds it, at a fixed price.

03

Nobody is watching tonight

Premium support covers critical issues 24/7 with a response within four hours.

04

The platform is the problem

If running a SIEM is taking more time than using one, compare the options in Wazuh vs Splunk, Sentinel and Elastic.

Questions

Questions about Wazuh troubleshooting

Why does my Wazuh agent show never connected?

The agent has enrolled but has never reported to the manager. Check that it can reach the manager on TCP 1514, that its client.keys entry matches the manager's, that its name is unique, that it is not newer than the manager, and, in a cluster, that the load balancer sends enrolment to the master node.

What does Wazuh dashboard server is not ready yet mean?

The dashboard cannot reach the indexer. It is normal for a short time after a restart. If it persists, check the indexer is running and has free disk, read the dashboard log, and check the dashboard still holds the correct indexer password after any password change.

Why is my Wazuh indexer yellow?

Some replica shards are unassigned. Use the shards and allocation explain APIs to find out why: usually a disk watermark, a shard limit, a missing node or a lifecycle policy. A healthy single-node Wazuh deployment should report green.

How do I fix disk usage exceeded flood-stage watermark?

Free disk space first, by adding storage or deleting indices you no longer need, then clear the read_only_allow_delete block if it remains. Set a lifecycle policy so it does not happen again.

Can the Wazuh agent be newer than the manager?

No. The manager must be the same version as its agents or newer, and the central components must all run the same version. Upgrade the manager before the agents.

Do you offer Wazuh support?

Yes. Standard support covers business hours with a response within 8 hours, from £595 + VAT a month; Premium covers critical issues 24/7 with a response within 4 hours, from £1,495 + VAT a month.

Wazuh troubleshooting

Stuck with a Wazuh problem?

Thirty minutes on what is happening and what you have tried. If it is quick, we will say so; if not, we will price the fix.