Wazuh is one of the most powerful open-source security monitoring and SIEM platforms available today, but its extensive feature set also means that diagnosing problems can become complicated.

A single issue may involve multiple services, configuration files, TLS certificates, APIs, or even external components like Filebeat and OpenSearch.

This comprehensive Wazuh troubleshooting guide serves as a central resource for identifying, diagnosing, and resolving the most common problems encountered in Wazuh deployments.

Whether you’re dealing with disconnected agents, dashboard failures, indexing problems, authentication errors, or cluster health issues, you’ll find a structured workflow for narrowing down the root cause before applying the appropriate fix.

Instead of treating each symptom independently, this guide focuses on understanding how the entire Wazuh ecosystem works together so you can troubleshoot more efficiently and avoid unnecessary downtime.

Why Troubleshooting Wazuh Can Be Challenging

Unlike standalone security tools, Wazuh consists of several tightly integrated components that depend on one another to process security events successfully.

For example:

An agent may appear connected while alerts never reach the dashboard.
The dashboard may load successfully but fail to display data because the indexer is unhealthy.
Filebeat may silently stop forwarding alerts even though the manager is functioning normally.
A TLS certificate mismatch can prevent communication without generating obvious user-facing errors.

Because failures often propagate across multiple services, the visible symptom is not always where the underlying problem originates.

This layered architecture requires administrators to understand service dependencies rather than troubleshooting each component in isolation.

According to the Wazuh Dashboard Not Loading? Complete Troubleshooting Guide, many dashboard issues ultimately originate from indexer connectivity, authentication failures, or unavailable backend services rather than the dashboard itself.

Likewise, Fixing Wazuh 502 Bad Gateway: Troubleshooting Guide demonstrates how reverse proxy errors frequently mask failures occurring in downstream Wazuh services.

How Wazuh’s Multi-Component Architecture Affects Issue Diagnosis

One of the biggest challenges in Wazuh troubleshooting is understanding where data travels throughout the platform.

A typical security event follows a chain similar to this:

A Wazuh agent collects logs or telemetry.
The Wazuh manager analyzes the event.
Filebeat forwards alerts.
The Wazuh indexer stores the data.
The Wazuh Dashboard queries OpenSearch.
Users view alerts through the web interface.

Because every stage depends on the previous one, failures are cumulative.

For example:

If agents cannot reach the manager, no events are analyzed.
If Filebeat fails, analyzed alerts never reach the indexer.
If the indexer becomes unhealthy, dashboards display empty results.
If dashboard authentication fails, data exists but cannot be accessed.

Experienced Wazuh administrators therefore recommend tracing the complete data path instead of focusing only on the visible symptom.

As the official Wazuh documentation explains, understanding component interactions dramatically simplifies diagnosing deployment issues.

Who This Guide Is For

This guide is designed for anyone responsible for deploying, operating, or maintaining Wazuh environments, including:

Security engineers maintaining enterprise SIEM infrastructure
SOC analysts investigating missing alerts or dashboard issues
System administrators managing Linux or Windows servers
DevOps engineers deploying Wazuh with Docker or Kubernetes
Platform engineers responsible for OpenSearch clusters
Consultants supporting customer Wazuh deployments

Whether you’re managing a small standalone installation or a distributed production cluster, the troubleshooting methodology presented here scales across both environments.

How to Use This Guide to Quickly Locate the Appropriate Fix

Rather than reading every section sequentially, use this pillar guide as a troubleshooting hub.

Start by identifying the affected component, then jump directly to the specialized troubleshooting guide for that issue.

For example:

Agent connectivity issues → Wazuh Agent Not Connecting to Manager? 12 Proven Fixes
API authentication problems → Wazuh API Authentication Failed? Causes and Solutions
Certificate errors → How to Fix Wazuh Certificate Errors
Dashboard startup failures → How to Fix “Wazuh Dashboard Server Is Not Ready Yet” (Step-by-Step)
Index problems → Troubleshooting “No Matching Indices Found” Error in Wazuh Dashboard
Cluster health issues → How to Fix a Yellow Cluster Status in Wazuh Indexer

Following the systematic workflow in this guide first, and then diving into the relevant cluster article, will help you resolve issues more quickly while avoiding unnecessary configuration changes.

Understanding the Wazuh Architecture Before Troubleshooting

Understanding how Wazuh processes data is one of the fastest ways to reduce troubleshooting time.

Many administrators immediately inspect the component displaying the error, but the root cause often lies several layers upstream.

Knowing how each service interacts with the others allows you to isolate failures methodically instead of relying on trial and error.

Wazuh Components at a Glance

Wazuh Manager

The Wazuh Manager is the central processing engine.

It:

Receives events from agents
Applies decoders and rules
Performs correlation
Executes active responses
Generates security alerts

If the manager becomes unavailable, nearly every other component eventually experiences downstream failures.

Wazuh Agents

Agents run on monitored endpoints including:

Linux servers
Windows systems
macOS devices
Cloud instances
Containers

They collect:

System logs
Security events
File integrity changes
Vulnerability information
Security Configuration Assessment (SCA) results

Communication failures between agents and the manager are among the most common Wazuh issues.

For detailed diagnostics, see:

Wazuh Agent Not Connecting to Manager? 12 Proven Fixes

Wazuh Indexer

The Wazuh Indexer stores alerts generated by the manager using OpenSearch.

It is responsible for:

Index creation
Search performance
Data storage
Cluster replication
Query execution

Cluster health problems can prevent dashboards from displaying alerts even when event collection continues successfully.

Wazuh Dashboard

The Dashboard provides visualization and investigation capabilities.

It communicates with:

OpenSearch APIs
Authentication services
Wazuh API
Security plugins

Dashboard problems are frequently symptoms of backend issues rather than frontend failures.

Related guides include:

Filebeat

Filebeat forwards alerts from the manager to the indexer.

If Filebeat stops working:

Alerts continue being analyzed.
No new data reaches OpenSearch.
Dashboards appear stale.

OpenSearch APIs

OpenSearch APIs provide:

Authentication
Search queries
Index management
Cluster health
Security plugin communication

Many dashboard and API issues ultimately trace back to OpenSearch permission or connectivity problems.

Certificate Infrastructure

Modern Wazuh deployments rely heavily on TLS certificates.

Certificates secure communication between:

Agents and managers
Dashboard and indexer
Filebeat and indexer
API clients
Cluster nodes

Expired or mismatched certificates often generate misleading connection errors.

Related guide:

How to Fix Wazuh Certificate Errors

How Data Flows Through Wazuh

Understanding the event pipeline makes troubleshooting significantly easier.

Agent Collection

Agents continuously collect telemetry from monitored endpoints.

Manager Analysis

The manager decodes, correlates, enriches, and classifies incoming events using built-in rules and custom decoders.

Indexing

Processed alerts are forwarded through Filebeat and indexed into OpenSearch.

Dashboard Visualization

The Dashboard retrieves indexed data using OpenSearch APIs and presents it through dashboards, searches, and visualizations.

Alert Generation

Alerts become searchable, trigger notifications, and may launch active response actions depending on configured rules.

Why Understanding the Workflow Speeds Up Troubleshooting

Most Wazuh failures affect only one stage of the pipeline.

Once you identify where the data stops flowing, you’ve dramatically reduced the scope of your investigation.

Instead of examining dozens of configuration files simultaneously, you can focus on the affected service.

This systematic approach is also recommended throughout the official Wazuh documentation.

A Systematic Wazuh Troubleshooting Workflow

The most effective administrators follow the same diagnostic process every time instead of jumping immediately to configuration changes.

This repeatable workflow helps isolate failures quickly while minimizing unnecessary downtime.

Step 1: Identify Which Component Is Failing

Begin by determining where the failure occurs.

Possible failure points include:

Agent

Symptoms:

Agent disconnected
No logs received
Registration failures
Missing vulnerability data

Related articles:

Manager

Typical indicators include:

Rules not executing
Missing alerts
Manager crashes
Core dumps

Indexer

Watch for:

Yellow cluster status
Red cluster
Missing indices
Slow searches

Related articles:

Dashboard

Common symptoms:

Login failures
Blank dashboards
Loading loops
“Server is not ready yet”
HTTP 502 errors

Related guides:

Filebeat

Symptoms include:

Alerts not indexed
Connection refused
Output failures

API

Typical issues include:

Authentication failures
Permission errors
TLS problems

Step 2: Verify Service Health

Before modifying configuration files, confirm that all required services are actually running.

Linux Services

Check service status using systemd.

Verify:

Active state
Startup failures
Restart loops
Dependency failures

Windows Services

Confirm:

Wazuh Agent service status
Event Viewer errors
Automatic startup configuration

Docker Deployments

Inspect:

Container health
Restart counts
Container logs
Mounted volumes
Network configuration

Kubernetes Deployments

Validate:

Pod health
CrashLoopBackOff events
Readiness probes
Persistent volume status
Service endpoints

Step 3: Review Relevant Log Files

Logs provide the most direct evidence of what is failing.

Manager Logs

Review manager logs for:

Decoder failures
Rule errors
Authentication issues
Cluster communication problems

Agent Logs

Look for:

Connection retries
Registration failures
TLS errors
Configuration parsing problems

Dashboard Logs

Inspect dashboard logs for:

Authentication failures
Plugin initialization errors
OpenSearch connectivity issues

Indexer Logs

Focus on:

Cluster allocation
Node failures
Security plugin messages
Disk watermark warnings

Filebeat Logs

Common findings include:

Connection refused
TLS negotiation failures
Authentication errors
Output retry loops

Step 4: Verify Network Connectivity

Many Wazuh issues ultimately stem from networking rather than software bugs.

Check:

Ports

Ensure required ports are open between components.

Firewalls

Verify that host-based and network firewalls are not blocking communication.

DNS

Confirm that all hostnames resolve correctly.

TLS Connectivity

Validate certificate trust chains and encrypted communication between services.

Google’s Site Reliability Engineering guidance emphasizes that structured verification of dependencies, including networking and service health, reduces mean time to resolution (MTTR) by avoiding unnecessary configuration changes.

Step 5: Validate Configuration Files

Many failures originate from small configuration mistakes.

Review every recently modified configuration file.

ossec.conf

Validate:

XML syntax
Agent configuration
Decoders
Rules
Integrations

Filebeat Configuration

Verify:

Output destinations
Authentication
Certificates
Index settings

Dashboard Configuration

Inspect:

OpenSearch endpoints
Authentication settings
SSL configuration

Indexer Configuration

Review:

Cluster discovery
Node roles
Security plugin configuration
TLS settings

Step 6: Check Version Compatibility

Version mismatches frequently appear after upgrades.

Always verify:

Supported Versions

Ensure every component belongs to a supported compatibility matrix.

Upgrade Mismatches

Avoid mixing incompatible manager, dashboard, indexer, and agent versions.

Plugin Compatibility

Confirm that OpenSearch plugins, dashboard plugins, and security components match the installed Wazuh release.

The official Wazuh release documentation recommends upgrading related components together whenever possible to avoid compatibility issues that manifest as authentication failures, dashboard errors, or cluster instability.

Wazuh Troubleshooting by Component

One of the fastest ways to troubleshoot Wazuh is to identify which component is responsible for the failure.

Although symptoms often appear in the Dashboard, the underlying issue may actually originate from the agent, manager, Filebeat, indexer, or API.

This section organizes the most common problems by component, allowing you to quickly narrow your investigation and jump to a dedicated troubleshooting guide for detailed remediation.

Wazuh Agent Issues

The Wazuh agent is the foundation of the entire monitoring pipeline.

Every security event begins on an endpoint before being forwarded to the manager for analysis.

If agents cannot register, authenticate, collect logs, or communicate with the manager, no alerts will ever reach the dashboard.

Fortunately, most agent-related issues fall into a handful of categories:

Registration failures
Network connectivity problems
Authentication errors
Service startup failures
Configuration mistakes
Certificate problems

By identifying which category your issue belongs to, you can usually resolve agent problems much faster.

Wazuh Agent Not Connecting to Manager

One of the most common Wazuh support issues occurs when agents remain disconnected from the manager.

Typical symptoms include:

Agent status remains Disconnected
Registration completes but no data is received
Connection timeout errors
Authentication failures
Manager never receives endpoint logs

Common causes include:

Firewall rules blocking communication
Incorrect manager IP address or hostname
Closed registration ports
TLS certificate problems
DNS resolution failures
Incorrect agent configuration
Version incompatibilities

Because connectivity failures can originate from either the agent or the manager, always verify both sides before modifying configuration files.

Wazuh Agent Not Connecting to Manager? 12 Proven Fixes

Duplicate Name or IP During Agent Registration

During agent enrollment, administrators occasionally encounter duplicate registration errors indicating that another agent already exists with the same name or IP address.

These errors commonly appear after:

Restoring virtual machines
Cloning servers
Reinstalling operating systems
Reusing agent names
Migrating infrastructure

Attempting to register duplicate agents can create inconsistent inventories and prevent new endpoints from appearing correctly in the Dashboard.

Best practice is to remove obsolete registrations before enrolling replacement systems.

For a complete walkthrough, see:

Resolving Duplicate Name or IP Errors in Wazuh Agent Registration

Agent Password Mismatch During Registration

When using authd for agent enrollment, registration may fail with password mismatch or authentication errors.

Typical symptoms include:

Registration rejected
Invalid password messages
Authentication timeout
Agent never appears in the manager

Possible causes include:

Incorrect enrollment password
Authentication daemon configuration errors
Expired registration credentials
Mismatched manager configuration
Incorrect automation scripts

Always verify the manager’s authentication configuration before generating new agent keys.

For detailed remediation steps, read:

Fix Authd Registration Failures: Wazuh Agent Password Mismatched Guide

Windows Agent Service Starts Then Stops

Windows administrators frequently report that the Wazuh Agent service starts successfully before stopping again within a few seconds.

Unlike simple service failures, this behavior usually indicates that the agent encountered a fatal error during initialization.

Possible root causes include:

Invalid configuration files
Missing dependencies
Permission issues
Corrupted installation
XML syntax errors
Unsupported module configuration

Windows Event Viewer and the Wazuh agent log should always be your first diagnostic resources when investigating service startup failures.

For a complete troubleshooting workflow, visit:

Why the Wazuh Windows Agent Service Starts Then Stops (And How to Fix It)

ossec.conf Syntax Errors

The ossec.conf file controls nearly every aspect of Wazuh agent behavior.

Even a single malformed XML tag can prevent the agent from starting correctly.

Common configuration mistakes include:

Missing closing tags
Invalid XML syntax
Unsupported configuration directives
Duplicate elements
Incorrect module placement
Typographical errors

Configuration validation should always be performed before restarting production agents.

The official Wazuh documentation recommends validating configuration changes carefully because malformed XML can prevent modules from loading correctly and interrupt data collection.

For step-by-step repair instructions, see:

How to Fix ossec.conf Syntax Errors in Wazuh Agents

Wazuh Manager Issues

The Wazuh Manager is the analytical core of the platform.

It receives events from every connected agent, processes decoders and rules, performs correlation, generates alerts, and coordinates active response actions.

Because nearly every component depends on the manager, failures here often have widespread consequences throughout the deployment.

Manager-related problems commonly include:

Service crashes
Core dumps
Database failures
Rule processing errors
Decoder issues
Resource exhaustion
Queue bottlenecks
Internal worker crashes

When investigating manager issues, always examine both system resource utilization and manager log files before making configuration changes.

Wazuh Manager Core Dumps

A manager core dump indicates that the Wazuh Manager process terminated unexpectedly due to a fatal runtime error.

Common symptoms include:

Manager service repeatedly restarting
Segmentation faults
Missing alerts
Empty event queues
Sudden interruption of agent communication

Potential causes include:

Software defects
Memory corruption
Faulty custom decoders
Resource exhaustion
Incompatible libraries
Unexpected operating system changes

If core dumps occur repeatedly, collect diagnostic information before restarting services so the root cause can be analyzed accurately.

For complete troubleshooting guidance, read:

Troubleshooting Wazuh Manager Core Dumps

wazuh-db Worker Thread Crashes

The wazuh-db service manages internal databases used by several Wazuh modules.

Worker thread crashes can disrupt database operations, slow event processing, and affect multiple platform features simultaneously.

Common symptoms include:

Database-related errors in manager logs
Intermittent service instability
High CPU usage
Delayed event processing
Failed queries
Repeated worker restart messages

Possible root causes include:

Database corruption
Resource starvation
Concurrency issues
Disk I/O bottlenecks
Software bugs
Version incompatibilities

When diagnosing recurring worker thread crashes, monitor system resources alongside Wazuh logs to determine whether the failure is caused by infrastructure limitations or an application-level issue.

Google’s Site Reliability Engineering guidance emphasizes correlating application logs with system metrics such as CPU, memory, storage latency, and process restarts to reduce mean time to resolution when debugging distributed systems.

Wazuh Dashboard Issues

The Wazuh Dashboard is the primary interface for monitoring alerts, investigating security events, and managing the platform.

However, because the dashboard depends on several backend services, including the Wazuh Indexer, OpenSearch APIs, authentication services, and the Wazuh Manager, many dashboard problems are actually symptoms of failures elsewhere in the deployment.

For example, a dashboard that refuses to load may be caused by:

Unhealthy indexer nodes
Authentication failures
TLS certificate problems
Missing indices
Backend service outages
Version incompatibilities following an upgrade
Failed migration tasks

Rather than focusing solely on the web interface, always verify that the supporting services are functioning correctly before troubleshooting the dashboard itself.

Dashboard Not Loading

One of the most common administrator complaints is that the Wazuh Dashboard never finishes loading or displays only a blank page.

Typical symptoms include:

White or blank browser window
Endless loading spinner
HTTP 500 errors
HTTP 502 errors
Failed API requests
Missing visualizations

The underlying causes often include:

Dashboard service failure
Indexer connectivity issues
Authentication problems
Reverse proxy configuration errors
Browser cache corruption
Incorrect SSL configuration
OpenSearch security plugin failures

Because the dashboard is only the presentation layer, administrators should first verify backend connectivity before reinstalling or reconfiguring the UI.

For a complete troubleshooting workflow, see:

Wazuh Dashboard Not Loading? Complete Troubleshooting Guide

Dashboard Server Is Not Ready Yet

The message “Wazuh Dashboard server is not ready yet” typically appears when the dashboard starts successfully but cannot complete initialization.

Common causes include:

Indexer unavailable
OpenSearch authentication failures
TLS certificate mismatches
Incomplete startup sequence
Plugin initialization failures
Backend timeout errors

In many environments, restarting the dashboard alone will not resolve the issue because the actual failure occurs in one of its dependencies.

The official Wazuh documentation recommends confirming indexer health, authentication settings, and service availability before modifying dashboard configuration files.

For detailed recovery steps, read:

How to Fix “Wazuh Dashboard Server Is Not Ready Yet”

Kibana Server Is Not Ready Yet

Older Wazuh deployments that integrate with Kibana may display the familiar message:

“Kibana server is not ready yet.”

Although this error appears similar to the Wazuh Dashboard startup message, the root causes are often slightly different.

Common reasons include:

Elasticsearch or OpenSearch unavailable
Kibana plugin initialization failures
Saved object migration problems
Authentication errors
Cluster health issues
Version incompatibilities

Administrators maintaining legacy deployments should verify the health of both the search backend and Kibana services before attempting upgrades.

For a complete diagnostic guide, see:

How to Fix kibana server is not ready yet Using Wazuh

Infinite Login Loop

After upgrading Wazuh, some users successfully authenticate only to be redirected back to the login page repeatedly.

This infinite login loop is commonly associated with:

Session cookie problems
Authentication plugin incompatibilities
Browser cache issues
Security configuration changes
Version mismatches
Incomplete migrations

Because login loops frequently occur immediately after upgrades, administrators should verify that every Wazuh component, including the dashboard, indexer, manager, and plugins, is running compatible versions.

For a complete repair guide, visit:

How to Stop the Infinite Wazuh Login Loop After a Version Upgrade

No Matching Indices Found

If the dashboard reports “No Matching Indices Found,” the problem usually lies within the indexing pipeline rather than the dashboard itself.

Typical causes include:

Missing index templates
Filebeat failures
Index creation problems
Incorrect index patterns
Data ingestion failures
OpenSearch cluster issues

When this error appears, verify whether new alerts are reaching the indexer before rebuilding dashboard objects.

For detailed troubleshooting instructions, read:

Troubleshooting “No Matching Indices Found” Error in Wazuh Dashboard

Clear Stuck Migration Indices

Major version upgrades occasionally leave migration indices in an incomplete state.

Symptoms may include:

Dashboard startup failures
Endless migrations
Login errors
Saved object failures
Dashboard upgrade interruptions

Migration issues are usually caused by:

Interrupted upgrades
Index permission problems
Cluster instability
Version incompatibilities
Failed background tasks

Before deleting migration indices, verify that all services have completed the upgrade successfully and that backups are available if recovery becomes necessary.

For the safest recovery procedure, see:

How to Clear Stuck Migration Indices in Wazuh Dashboard

Wazuh Indexer Issues

The Wazuh Indexer is responsible for storing, indexing, and serving security events.

Even if agents, managers, and Filebeat are functioning correctly, dashboard searches will fail if the indexer is unhealthy.

Nearly every visualization in Wazuh depends on a healthy search cluster.

When index health deteriorates, administrators may experience:

Missing alerts
Slow searches
Dashboard errors
Delayed indexing
Failed API queries
Cluster instability

Because the indexer serves as the platform’s data store, maintaining cluster health should be considered a high operational priority.

Yellow Cluster Status

A Yellow cluster status indicates that all primary shards are available, but one or more replica shards have not been successfully allocated.

Although the platform continues operating, a prolonged yellow status reduces redundancy and increases the risk of data loss if another node fails.

Common causes include:

Single-node deployments
Insufficient data nodes
Disk watermark limits
Shard allocation restrictions
Node failures
Network connectivity problems
Replica configuration issues

Administrators should not ignore a persistent yellow status, especially in production environments, as it often serves as an early warning of larger infrastructure problems.

According to the OpenSearch documentation, cluster health should be monitored continuously because shard allocation issues directly affect search availability, resilience, and recovery operations.

For a complete troubleshooting workflow, see:

How to Fix a Yellow Cluster Status in Wazuh Indexer

Filebeat Issues

Filebeat is a critical data shipping component in many Wazuh deployments.

It acts as the transport layer responsible for forwarding processed alerts from the Wazuh Manager to the Wazuh Indexer (OpenSearch).

Even when the manager is functioning correctly and agents are actively generating alerts, a failure in Filebeat will completely break the indexing pipeline.

Because of its role as a relay service, Filebeat issues often present as “silent failures” where alerts are generated but never appear in the dashboard.

Common symptoms of Filebeat-related issues include:

Alerts missing from the dashboard despite active agent reporting
Indexer receiving no new data
Filebeat service repeatedly restarting
Connection errors in logs
Backpressure or queue overflow warnings
Delayed or partial indexing of events

When troubleshooting Filebeat, always validate connectivity to the indexer, certificate validity, and output configuration before assuming upstream issues.

Filebeat Connection Refused

A “connection refused” error indicates that Filebeat is unable to establish a TCP connection to the Wazuh Indexer.

This is one of the most common Filebeat failures and typically points to network-level or service-level issues rather than configuration syntax problems.

Typical symptoms include:

Filebeat continuously retrying connections
No events reaching OpenSearch
Log entries showing connection failures
Backlog buildup in Filebeat queues

Common root causes include:

Indexer service is down or restarting
Incorrect IP address or hostname in Filebeat output configuration
Firewall blocking port 9200 or configured OpenSearch port
TLS/SSL misconfiguration between Filebeat and Indexer
DNS resolution issues
Cluster not fully initialized

Because Filebeat sits between the manager and indexer, failures here create a complete break in the ingestion pipeline.

For a step-by-step fix guide, see:

Resolving Filebeat Connection Refused Errors in Wazuh Deployments

Detection and Monitoring Issues

Detection and monitoring issues are particularly misleading because they often occur even when the underlying infrastructure appears healthy.

In these cases, Wazuh components may be running correctly, logs may be flowing, and the indexer may be operational, but specific detection features fail to produce expected results.

These problems usually originate from:

Misconfigured rules or decoders
Disabled modules
API or integration failures
Incorrect thresholds or policies
Missing dependencies for analysis engines
Configuration drift after upgrades

Unlike infrastructure failures, detection issues require a deeper understanding of Wazuh’s internal rule-processing and analysis pipeline.

Vulnerability Detection Not Working

When vulnerability detection fails, Wazuh agents may still report system information, but vulnerability data never appears in the dashboard.

Symptoms include:

Empty vulnerability dashboards
No CVE results
Missing package scan data
Stale vulnerability information
Scan jobs not triggering

Common causes include:

Vulnerability detector module disabled
Outdated vulnerability feeds
Agent inventory collection issues
Manager analysis delays
Indexing pipeline interruptions
Version mismatches between components

Because vulnerability detection depends on both agent-side data collection and manager-side analysis, failures can occur at multiple points in the pipeline.

For a detailed fix guide, see:

Wazuh Vulnerability Detection Not Working? Here’s How to Fix It

Email Alerts Not Working

Email alerts are commonly used for SOC notification workflows, but failures often occur due to integration or configuration issues rather than detection problems.

Symptoms include:

Alerts visible in dashboard but no emails sent
SMTP authentication failures
Delayed notifications
Partial alert delivery
Silent integration failures

Common root causes include:

Incorrect SMTP configuration
Authentication failures with mail servers
TLS issues with email providers
Disabled alerting rules
Misconfigured integrations
Network restrictions on outbound mail ports

Because Wazuh generates alerts independently of notification delivery, it is important to separate detection correctness from alert delivery success.

For full troubleshooting steps, see:

Wazuh Email Alerts Not Working? Complete Fix Guide

Custom Decoder Isn’t Matching

Custom decoders are essential for parsing non-standard logs, but when they fail to match events, Wazuh effectively stops interpreting incoming data correctly.

Symptoms include:

Raw logs appear but no alerts generated
Decoder test failures
Missing rule matches
Logtest showing no output
Events bypassing analysis stage

Common causes include:

Incorrect regex patterns
Misaligned log formats
Decoder priority conflicts
Syntax errors in decoder XML
Changes in upstream log structure
Improper rule linkage

Because decoding is the first step in Wazuh’s analysis pipeline, failures here prevent all downstream detection logic from triggering.

For a deep dive into decoder debugging, see:

Custom Decoder Isn’t Matching: Wazuh Logtest Deep Dive

Syslog Port 514 Not Receiving Logs

Syslog ingestion issues are common in environments where Wazuh is used as a centralized log collector.

When port 514 stops receiving logs, administrators typically observe:

Missing syslog events
Empty log streams
No UDP/TCP traffic ingestion
Firewall-related connection drops
Intermittent log loss

Common causes include:

Port 514 blocked by firewall rules
Syslog daemon not listening
Incorrect protocol configuration (TCP vs UDP)
SELinux or AppArmor restrictions
Competing services using the same port
Misconfigured remote syslog senders

Since syslog ingestion depends heavily on network configuration, always validate port accessibility before modifying Wazuh rules or decoders.

For detailed troubleshooting instructions, see:

Troubleshoot Wazuh Syslog Port 514 Ingestion

SCA Scan Failures

Security Configuration Assessment (SCA) scans evaluate endpoint security baselines, but failures often occur even when agents and managers are functioning correctly.

Symptoms include:

Missing SCA reports
Incomplete scan results
Failed policy execution
Empty compliance dashboards
Intermittent scan completion

Common causes include:

Disabled SCA module on agents
Permission issues executing system checks
Unsupported commands or shell environments
Misconfigured policies
Resource constraints on endpoints
Command execution restrictions

A frequent issue is missing shell wrappers for command-based rules, especially in hardened Linux environments where direct command execution is restricted.

For a complete remediation guide, see:

Fixing Wazuh SCA Scan Failures: Adding Shell Wrappers to Command Rules

Authentication and Security Issues

Authentication and security-related failures in Wazuh typically originate from misconfigured credentials, TLS certificate mismatches, or broken trust relationships between components.

These issues are particularly disruptive because they can block access even when all backend services are fully operational.

Unlike performance or ingestion problems, authentication failures often present as hard stops, requests fail immediately with errors such as 401 Unauthorized, 403 Forbidden, or TLS handshake failures.

Common root causes include:

Invalid or expired API credentials
Broken or mismatched TLS certificates
Incorrect role-based access control (RBAC) configuration
OpenSearch security plugin misconfiguration
Clock drift affecting token validation
Version mismatches in authentication modules

Because Wazuh relies heavily on secure communication between distributed components, even minor certificate or credential issues can cascade into system-wide access failures.

API Authentication Failed

The Wazuh API is a core interface used by the dashboard, automation tools, and external integrations.

When API authentication fails, it can disrupt both UI functionality and programmatic access.

Typical symptoms include:

401 Unauthorized responses from API calls
Dashboard failing to load security data
Authentication errors in logs
Integration scripts failing unexpectedly
Token validation errors

Common causes include:

Incorrect username or password
Expired or invalid API tokens
Misconfigured API authentication settings
Role or permission misalignment
TLS certificate verification failures
Clock synchronization issues between nodes

Because the API sits between the dashboard and backend services, authentication failures here often appear as broader dashboard or access issues.

For a detailed breakdown of root causes and fixes, see:

Wazuh API Authentication Failed? Causes and Solutions

Certificate Errors

Certificate-related issues are among the most common and most disruptive problems in distributed Wazuh deployments.

They affect communication between nearly every major component, including agents, managers, indexers, dashboards, and APIs.

Typical symptoms include:

TLS handshake failures
Connection refused errors with SSL messages
Dashboard unable to connect to indexer
Agent registration failures
“certificate verify failed” errors
Intermittent connectivity between components

Common causes include:

Expired certificates
Incorrect certificate chain configuration
Mismatched hostnames (CN/SAN issues)
Self-signed certificate trust failures
Improper certificate distribution across nodes
Misconfigured TLS parameters in Filebeat or OpenSearch

Because Wazuh enforces secure communication across its architecture, certificate misconfiguration can completely isolate components even when network connectivity is otherwise functional.

For a step-by-step remediation guide, see:

How to Fix Wazuh Certificate Errors

Proxy and Web Server Issues

Wazuh deployments often sit behind reverse proxies or web servers such as Nginx, Apache, or cloud load balancers.

While these layers provide security, routing, and TLS termination, they can also introduce additional failure points that affect dashboard accessibility.

Proxy-related issues typically manifest as HTTP errors, timeout failures, or incomplete responses, even when internal Wazuh services are fully operational.

Common symptoms include:

Dashboard inaccessible externally but working internally
HTTP 502 / 503 / 504 errors
Partial page loads or broken UI components
Authentication loops through proxy redirects
TLS termination mismatches
WebSocket connection failures

Common root causes include:

Misconfigured upstream server definitions
Incorrect proxy headers (Host, X-Forwarded-For)
Backend service downtime (dashboard or indexer)
TLS certificate mismatch between proxy and backend
Timeout misconfiguration
Firewall blocking internal service ports

Because reverse proxies sit at the edge of the architecture, they often mask backend issues as frontend failures.

502 Bad Gateway

A 502 Bad Gateway error indicates that the reverse proxy received an invalid or no response from an upstream service.

In Wazuh deployments, this usually means the dashboard or backend service is unavailable or unreachable.

Typical symptoms include:

Browser displays “502 Bad Gateway”
Dashboard intermittently unreachable
Reverse proxy error logs showing upstream failures
Backend services running but not responding correctly
Load balancer health check failures

Common causes include:

Wazuh Dashboard service not running
Indexer or OpenSearch unavailable
Incorrect proxy_pass configuration
Firewall blocking internal traffic between proxy and backend
TLS handshake failure between proxy and dashboard
Backend service overload or crash

Because 502 errors originate at the proxy layer, administrators should always verify backend service health before modifying proxy configurations.

For a full troubleshooting workflow, see:

Fixing Wazuh 502 Bad Gateway: Troubleshooting Guide

Preventive Maintenance Best Practices

Preventing Wazuh issues is significantly more efficient than reacting to them.

Because Wazuh is a distributed system with tightly coupled components, small configuration drift, certificate expiration, or version mismatch can quickly escalate into system-wide outages.

A structured preventive maintenance strategy reduces downtime, improves alert reliability, and ensures long-term platform stability.

Keep All Wazuh Components on Compatible Versions

Version mismatch is one of the most common hidden causes of instability in Wazuh deployments.

To avoid compatibility issues:

Keep Wazuh Manager, Dashboard, Indexer, and Agents aligned
Avoid partial upgrades across components
Validate plugin compatibility after updates
Follow official release matrices before upgrading

Inconsistent versions often result in authentication errors, dashboard failures, or indexing issues that are difficult to diagnose without first checking version alignment.

Monitor Cluster Health Continuously

The Wazuh Indexer (OpenSearch) cluster is the backbone of all search and visualization functionality.

Key metrics to monitor:

Cluster status (green, yellow, red)
Shard allocation
Node availability
Disk watermark levels
Query latency

Early detection of a yellow cluster status can prevent more severe outages.

For reference troubleshooting:

How to Fix a Yellow Cluster Status in Wazuh Indexer

Validate Certificates Before They Expire

TLS certificates govern communication between nearly all Wazuh components.

Best practices include:

Tracking certificate expiration dates
Automating renewal processes
Validating certificate chains after renewal
Ensuring hostname consistency (SAN/CN validation)

Expired or mismatched certificates are a leading cause of silent communication failures between agents, managers, dashboards, and indexers.

Back Up Configuration Files

Configuration files define the behavior of every Wazuh component.

Critical files to back up include:

ossec.conf
Filebeat configuration
Dashboard configuration
Indexer settings
Custom decoders and rules
Security plugin configurations

Backups should be versioned and stored externally to ensure recovery after failed upgrades or misconfigurations.

Test Upgrades in a Staging Environment

Upgrades can introduce breaking changes across components.

Before applying production upgrades:

Replicate production environment in staging
Validate version compatibility
Test dashboards and APIs
Verify agent connectivity
Confirm indexer health

This approach helps identify issues like login loops, index migration failures, or plugin incompatibilities before impacting production systems.

Monitor Disk Space and Index Growth

Wazuh relies heavily on disk-based indexing through OpenSearch.

Without proper monitoring:

Indexer performance degrades
Cluster status may turn yellow or red
Data ingestion may stop unexpectedly

Key monitoring areas include:

Disk usage per node
Index growth rate
Retention policies
Shard size distribution

Regularly Review Wazuh Logs

Logs are the most reliable source of truth for troubleshooting.

Administrators should routinely review:

Manager logs for rule and decoder errors
Agent logs for connectivity issues
Indexer logs for cluster health warnings
Dashboard logs for authentication failures
Filebeat logs for ingestion issues

Proactive log analysis often reveals issues before they impact production systems.

Automate Health Checks

Automation reduces mean time to detection (MTTD) for Wazuh issues.

Recommended checks include:

Service uptime monitoring
API health endpoints
Indexer cluster status checks
Agent connectivity verification
Disk and memory usage alerts

Automated monitoring ensures early detection of failures before they cascade across components.

Document Configuration Changes

Change tracking is essential in distributed systems like Wazuh.

Best practices include:

Maintaining version-controlled configuration files
Documenting every production change
Tracking upgrade history
Recording certificate updates
Logging rule and decoder modifications

Clear documentation simplifies rollback procedures and accelerates root cause analysis during incidents.

Quick Troubleshooting Checklist

When a Wazuh issue occurs, a structured checklist helps quickly narrow down the root cause before diving into deep diagnostics.

Are all Wazuh services running?

Verify that core services are active:

Wazuh Manager
Wazuh Agent
Wazuh Indexer
Wazuh Dashboard
Filebeat

Service failures often cascade into broader system issues.

Can agents reach the manager?

Check:

Network connectivity
Firewall rules
Manager IP/hostname configuration
Agent authentication status

Agent disconnects are one of the most common early failure indicators.

Is Filebeat forwarding alerts?

Validate:

Filebeat service status
Output configuration
Indexer connectivity
Log ingestion flow

If Filebeat fails, alerts will not reach the indexer.

Is the indexer cluster healthy?

Confirm:

Cluster status (green preferred)
Shard allocation
Node availability
Disk usage thresholds

A degraded cluster directly impacts search and dashboard functionality.

Are dashboard indices available?

Check:

Index patterns exist
Indices are being updated
No “No Matching Indices Found” errors
Data is present in OpenSearch

Are certificates valid?

Verify:

Expiration dates
Hostname matching (SAN/CN)
Trust chain integrity
TLS configuration consistency

Certificate issues can silently break communication across components.

Are required ports open?

Ensure connectivity between components:

Agent ↔ Manager ports
Manager ↔ Indexer ports
Dashboard ↔ Indexer ports
API communication ports

Firewall restrictions are a frequent hidden cause of failures.

Are versions compatible?

Check:

Manager, indexer, dashboard version alignment
Agent compatibility
Plugin consistency

Version mismatches often produce unexpected authentication or UI errors.

Are authentication credentials correct?

Validate:

API credentials
Dashboard login credentials
Role-based access settings
Token validity

Authentication failures frequently manifest as dashboard or API errors.

Have logs been reviewed for recent errors?

Always inspect:

Manager logs
Agent logs
Indexer logs
Dashboard logs
Filebeat logs

Logs typically contain the most direct explanation of the failure.

A disciplined approach combining this checklist with component-based troubleshooting significantly reduces mean time to resolution (MTTR) and improves overall Wazuh operational reliability.

Frequently Asked Questions (FAQ)

This section consolidates common Wazuh troubleshooting questions into concise, practical answers.

These reflect real-world operational issues encountered in production environments and are intended to help quickly narrow down root causes before deeper investigation.

Question: What is the first thing to check when Wazuh stops working?

The first step is always service health verification across all core components:

Wazuh Manager status
Wazuh Indexer cluster health
Wazuh Dashboard availability
Filebeat forwarding status
Agent connectivity

Most “Wazuh is down” incidents are actually caused by a single failing dependency rather than a complete system outage.

Question: Why is my Wazuh Dashboard unavailable?

Dashboard unavailability is typically caused by backend dependencies rather than the UI itself.

Common causes include:

Indexer cluster failures
Authentication issues
TLS certificate problems
Reverse proxy misconfiguration
Version incompatibilities after upgrades

For detailed troubleshooting steps, refer to dashboard-specific guides such as:

Wazuh Dashboard Not Loading? Complete Troubleshooting Guide

Question: How do I know whether the problem is with the agent or the manager?

A structured diagnostic approach helps isolate the issue:

If multiple agents are disconnected → likely manager or network issue
If only one agent fails → likely agent-side issue
If agents connect but no alerts appear → manager or Filebeat issue
If logs are missing entirely → ingestion pipeline issue

Checking agent logs and manager logs together usually reveals where the communication breakdown occurs.

Question: Why are alerts not appearing in the dashboard?

Missing alerts are commonly caused by breakdowns in the ingestion pipeline:

Filebeat not forwarding logs
Indexer not receiving data
Missing or corrupted indices
Cluster health degradation
Disabled rules or decoders

Start by verifying whether alerts exist in the indexer before assuming a dashboard issue.

Question: What causes Wazuh API authentication failures?

API authentication failures are typically caused by:

Incorrect credentials or tokens
Expired sessions
Role or permission misconfiguration
TLS certificate validation issues
Clock synchronization problems between systems

For a full breakdown, see:

Wazuh API Authentication Failed? Causes and Solutions

Question: How do I diagnose Filebeat issues in Wazuh?

Filebeat issues are best diagnosed by reviewing:

Filebeat service status
Output configuration to indexer
Log files for connection errors
Queue or backpressure warnings

A frequent failure mode is connection refused, which usually indicates indexer unavailability or firewall restrictions.

Question: What log files should I check first during Wazuh troubleshooting?

Start with the following priority order:

Wazuh Manager logs
Wazuh Agent logs
Filebeat logs
Indexer logs
Dashboard logs

Logs often contain direct error messages that immediately identify the failing component.

Question: How can I prevent common Wazuh issues after upgrades?

To reduce post-upgrade issues:

Upgrade all components together
Validate version compatibility beforehand
Test in a staging environment
Monitor migration indices
Verify dashboard and indexer health after upgrade
Clear stale sessions or cached authentication data

Many issues such as login loops or missing indices occur due to incomplete or partial upgrade sequences.

Question: When should I rebuild indices versus restoring from backup?

Rebuild indices when data is missing due to mapping issues, template errors, or ingestion problems
Restore from backup when there is data corruption, accidental deletion, or catastrophic cluster failure

Rebuilding is non-destructive, while restoring should be reserved for recovery scenarios.

Question: What tools are most useful for Wazuh troubleshooting?

Key tools include:

Wazuh logs (manager, agent, dashboard)
OpenSearch APIs for cluster inspection
Filebeat status and logs
Systemd service monitoring tools
Curl for API testing
Browser developer tools for dashboard debugging

Combining system-level and application-level diagnostics provides the fastest path to root cause identification.

Conclusion

Effective Wazuh troubleshooting depends on structured methodology rather than reactive debugging.

Because Wazuh operates as a distributed system composed of tightly interconnected services, isolating issues by component is essential for efficient resolution.

The most reliable approach is to systematically trace failures through the full data pipeline:

Agent → Manager → Filebeat → Indexer → Dashboard

This ensures that symptoms are not mistaken for root causes and prevents unnecessary configuration changes that may worsen the issue.

Throughout this guide, each major component has been broken down into its most common failure modes, supported by detailed internal troubleshooting resources.

These linked guides allow you to move quickly from diagnosis to resolution without losing visibility into system-wide dependencies.

For production environments, prevention is just as important as troubleshooting. Most Wazuh issues can be avoided through:

Proactive monitoring of service health and cluster status
Strict version compatibility across all components
Regular validation of TLS certificates and security configurations
Routine review of logs and system metrics
Structured change management and configuration documentation

When combined, these practices significantly reduce downtime, improve alert reliability, and ensure long-term stability of Wazuh deployments in production environments.

The Ultimate Wazuh Troubleshooting Guide: Fix Common Issues

Why Troubleshooting Wazuh Can Be Challenging

How Wazuh’s Multi-Component Architecture Affects Issue Diagnosis

Who This Guide Is For

How to Use This Guide to Quickly Locate the Appropriate Fix

Understanding the Wazuh Architecture Before Troubleshooting

Wazuh Components at a Glance

Wazuh Manager

Wazuh Agents

Wazuh Indexer

Wazuh Dashboard

Filebeat

OpenSearch APIs

Certificate Infrastructure

How Data Flows Through Wazuh

Agent Collection

Manager Analysis

Indexing

Dashboard Visualization

Alert Generation

Why Understanding the Workflow Speeds Up Troubleshooting

A Systematic Wazuh Troubleshooting Workflow

Step 1: Identify Which Component Is Failing

Agent

Manager

Indexer

Dashboard

Filebeat

API

Step 2: Verify Service Health

Linux Services

Windows Services

Docker Deployments

Kubernetes Deployments

Step 3: Review Relevant Log Files

Manager Logs

Agent Logs

Dashboard Logs

Indexer Logs

Filebeat Logs

Step 4: Verify Network Connectivity

Ports

Firewalls

DNS

TLS Connectivity

Step 5: Validate Configuration Files

ossec.conf

Filebeat Configuration

Dashboard Configuration

Indexer Configuration

Step 6: Check Version Compatibility

Supported Versions

Upgrade Mismatches

Plugin Compatibility

Wazuh Troubleshooting by Component

Wazuh Agent Issues

Wazuh Agent Not Connecting to Manager

Duplicate Name or IP During Agent Registration

Agent Password Mismatch During Registration

Windows Agent Service Starts Then Stops

ossec.conf Syntax Errors

Wazuh Manager Issues

Wazuh Manager Core Dumps

wazuh-db Worker Thread Crashes

Wazuh Dashboard Issues

Dashboard Not Loading

Dashboard Server Is Not Ready Yet

Kibana Server Is Not Ready Yet

Infinite Login Loop

No Matching Indices Found

Clear Stuck Migration Indices

Wazuh Indexer Issues

Yellow Cluster Status

Filebeat Issues

Filebeat Connection Refused

Detection and Monitoring Issues

Vulnerability Detection Not Working

Email Alerts Not Working

Custom Decoder Isn’t Matching

Syslog Port 514 Not Receiving Logs