Fix Wazuh Docker Compose Deployment

Deploying Wazuh with Docker Compose is one of the fastest ways to build a complete security monitoring environment.

Instead of installing each component manually, Docker Compose launches all required services together using predefined containers, networks, volumes, and configuration files.

This approach makes deployments consistent, portable, and much easier to reproduce across development, testing, and production environments.

However, a successful deployment depends on much more than simply running docker compose up.

Since multiple containers work together as a distributed application, a failure in one service can quickly prevent the entire stack from functioning correctly.

A misconfigured certificate, insufficient memory allocation, incorrect file permissions, or an unhealthy OpenSearch node can stop the Wazuh Dashboard from loading or prevent the Manager from processing security events.

What Wazuh Docker Compose deployment includes

The official Wazuh Docker Compose deployment provisions an entire security platform consisting of multiple interconnected services.

These typically include:

Wazuh Manager
Wazuh Indexer (OpenSearch)
Wazuh Dashboard
Filebeat
Docker networking
Persistent Docker volumes
SSL/TLS certificates for secure communication

Each component has its own role, but every service depends on the health of the others.

If one container becomes unavailable, the rest of the stack often experiences cascading failures.

Common deployment problems users encounter

Although Docker simplifies deployment, administrators frequently run into issues such as:

Containers entering restart loops
Dashboard showing connection or authentication errors
Wazuh Indexer failing cluster health checks
Docker volume permission problems
Certificate validation failures
Memory exhaustion and JVM crashes
Version mismatches between Wazuh components
Networking and DNS resolution failures between containers

Many of these problems stem from Docker configuration rather than Wazuh itself, making troubleshooting confusing for first-time users.

Symptoms of a failed deployment

Depending on which component fails, you may observe symptoms including:

Containers stuck in an Exited or Restarting state
The Dashboard displaying Server is not ready yet
Browser errors such as 502 Bad Gateway
Failed authentication between services
Indexer reporting a yellow or red cluster status
Missing security events inside the Dashboard
Docker Compose terminating during startup with configuration errors
Filebeat unable to publish logs

Ignoring these symptoms usually causes additional services to fail because each component depends on successful communication with the others.

What this guide covers

This guide provides a systematic approach to troubleshooting Wazuh Docker Compose deployments.

You’ll learn how the architecture works, identify the most common deployment failures, verify that every service is healthy, interpret Docker logs, diagnose networking and certificate issues, and restore a fully functioning deployment.

Throughout the guide, you’ll also find practical troubleshooting commands, recommended best practices, and links to official documentation where appropriate.

Expert Insight: The Wazuh documentation recommends using the official Docker Compose deployment files and keeping all Wazuh components on the same release version to avoid compatibility issues. The Docker documentation likewise emphasizes treating Compose files as declarative infrastructure so deployments remain consistent across environments.

Wazuh Dashboard Not Loading? Complete Troubleshooting Guide

Understanding the Wazuh Docker Compose Architecture

Understanding how the Docker Compose deployment is structured makes troubleshooting significantly easier.

Rather than functioning as a single application, Wazuh is a collection of tightly integrated services.

Each container performs a specific task while relying on other containers to complete the overall security monitoring workflow.

When one service becomes unavailable, dependent services often fail shortly afterward.

Knowing these relationships allows you to quickly determine where a deployment problem originates.

Wazuh Manager

The Wazuh Manager is the core of the platform.

It receives events from enrolled agents, analyzes security data, evaluates detection rules, triggers active responses, and forwards processed events for indexing.

Purpose

Its primary responsibilities include:

Receiving agent communications
Processing logs
Running decoders and rules
Performing vulnerability detection
Coordinating File Integrity Monitoring
Managing Active Response
Sending processed events to Filebeat

Without a healthy Manager container, agents cannot submit security events for analysis.

Default services

The Manager container typically includes:

Analysis daemon
Registration service (authd)
API service
Vulnerability detector
Active Response engine
Log analysis services

Ports

Common ports include:

1514 — Agent communication
1515 — Agent registration
55000 — REST API

Firewall rules and Docker port mappings must expose these ports correctly if external systems need access.

Wazuh Indexer

The Wazuh Indexer stores and indexes all security events received from Filebeat.

Role in data storage

Instead of storing alerts directly within the Manager, processed events are indexed for fast searching, visualization, and long-term retention.

The Indexer handles:

Alert indexing
Event storage
Search queries
Aggregations
Dashboard requests

OpenSearch integration

Modern Wazuh deployments use OpenSearch as the underlying search engine.

Because the Indexer manages cluster health, memory allocation, shards, and replicas, problems within OpenSearch frequently appear as Dashboard errors rather than obvious Indexer failures.

If the Indexer becomes unhealthy, the Dashboard usually cannot retrieve security data.

Wazuh Dashboard

The Dashboard provides the web interface administrators use to investigate alerts, manage agents, and visualize security data.

Web interface

From the Dashboard you can:

View alerts
Search indexed events
Manage agents
Configure dashboards
Investigate incidents
Monitor infrastructure health

Communication with the Indexer

The Dashboard does not communicate directly with the Manager for most visualized data.

Instead, it retrieves indexed events from the Wazuh Indexer over secure HTTPS connections.

If authentication, certificates, or networking fail, users often receive messages such as:

Server is not ready yet
Unable to retrieve version information
Authentication failures

Filebeat

Filebeat acts as the bridge between the Manager and the Indexer.

Log shipping responsibilities

Its primary duties include:

Reading Manager alert files
Forwarding alerts
Maintaining reliable delivery
Buffering events during temporary failures
Authenticating with the Indexer

If Filebeat stops working, alerts continue being generated but never appear inside the Dashboard.

Docker Network

Docker Compose automatically creates an isolated virtual network for all containers.

Container communication

Containers communicate using their service names instead of IP addresses.

For example:

manager
indexer
dashboard
filebeat

Docker handles internal routing automatically.

Internal DNS

Docker’s built-in DNS resolves service names between containers.

If the Docker network becomes corrupted or containers join different networks, hostname resolution fails, leading to connection timeouts and startup failures.

Persistent Volumes

Containers are designed to be disposable, but security data must persist.

Docker volumes ensure important files survive container recreation.

Data persistence

Persistent volumes commonly store:

Indexed alerts
Configuration files
Agent data
Dashboards
Cluster metadata

Without persistent storage, rebuilding containers can result in permanent data loss.

Certificate storage

Volumes also hold TLS certificates used for encrypted communication between:

Manager
Indexer
Dashboard
Filebeat

Incorrect ownership or missing certificate files are among the most common causes of deployment failures.

Expert Insight: Docker recommends storing application state in named volumes instead of container filesystems because containers are intended to be ephemeral. Likewise, Wazuh stores certificates and indexed data outside the containers to preserve state across upgrades and restarts.

Common Wazuh Docker Compose Deployment Problems

Even when using the official Docker Compose files, deployment issues can arise from resource limitations, networking problems, configuration mistakes, or incompatible software versions.

Understanding the most common failure scenarios makes diagnosis much faster.

Containers Continuously Restart

Restart loops typically indicate that a service crashes shortly after launching.

Common causes include:

Invalid configuration files
Missing certificates
Memory exhaustion
Failed health checks
Dependency services unavailable

Docker automatically restarts the container according to the restart policy, making the failure appear endless until the underlying problem is corrected.

One or More Containers Stay in “Exited” State

Containers that immediately exit usually encounter fatal startup errors.

Typical reasons include:

Invalid environment variables
Missing mounted volumes
Configuration syntax errors
File permission issues
Missing dependencies

Always inspect container logs before attempting repeated restarts.

Dashboard Cannot Connect to the Indexer

One of the most common deployment issues is a Dashboard that starts successfully but cannot retrieve data.

Possible causes include:

Incorrect credentials
TLS certificate problems
Indexer unavailable
Docker DNS failures
Firewall restrictions
Cluster health issues

Users may see messages such as Server is not ready yet or authentication failures.

Wazuh Manager Fails During Startup

The Manager may terminate during initialization because of:

Invalid ossec.conf
Broken XML syntax
Corrupted configuration files
Missing certificates
Resource exhaustion

Since the Manager performs extensive configuration validation during startup, even small syntax errors can prevent the container from running.

Certificate Validation Errors

The Docker deployment enables encrypted communication between services by default.

Common certificate problems include:

Expired certificates
Incorrect hostnames
Missing certificate files
Incorrect file permissions
Certificate authority mismatches

These issues often prevent secure communication between the Dashboard, Indexer, Filebeat, and Manager.

Related Guide:

How to Fix Wazuh Certificate Errors

Docker Compose Pull Errors

Before containers can start, Docker must download the required images.

Pull failures may occur because of:

Internet connectivity issues
Registry outages
Incorrect image names
Authentication problems
Rate limiting

Verifying image availability before deployment can eliminate unnecessary troubleshooting.

Docker Networking Problems

Container communication depends entirely on Docker networking.

Networking failures may involve:

Missing bridge networks
DNS resolution failures
Incorrect custom networks
Firewall restrictions
Port conflicts

Since every Wazuh component communicates across the Docker network, networking issues often affect multiple services simultaneously.

Volume Permission Issues

Persistent volumes frequently cause deployment failures, particularly on Linux hosts.

Common permission problems include:

Incorrect ownership
Read-only mounts
SELinux restrictions
Missing directories
UID/GID mismatches

These problems commonly prevent the Manager or Indexer from accessing their configuration or data directories.

Memory or JVM Errors

The Wazuh Indexer uses Java and requires sufficient heap memory.

If memory is exhausted, administrators may observe:

OutOfMemoryError
JVM crashes
Garbage collection pauses
Slow Dashboard responses
Cluster instability

Docker memory limits that are too restrictive can produce identical symptoms.

Version Compatibility Problems

Every component in a Wazuh deployment should use matching release versions.

Running different versions of:

Manager
Dashboard
Indexer
Filebeat

can lead to authentication failures, API incompatibilities, unsupported configuration options, and unexpected startup errors.

The safest practice is upgrading the complete stack together using the official release versions supported by Wazuh.

Prerequisites Before Troubleshooting

Before making changes to your Wazuh deployment, verify that the underlying Docker environment is healthy.

Many deployment failures are caused by missing dependencies, insufficient hardware resources, outdated Docker versions, or incorrect Compose files rather than Wazuh itself.

Spending a few minutes validating these prerequisites can eliminate many common issues before you begin more advanced troubleshooting.

Verify Docker Installation

First, ensure Docker Engine is installed and running.

Run:

docker --version

You should receive output similar to:

Docker version 28.x.x

Next, confirm the Docker daemon is running:

docker info

If Docker cannot connect to the daemon, start the Docker service before continuing.

On Linux:

sudo systemctl status docker

sudo systemctl start docker

Verify Docker Compose Version

Modern Docker installations use the integrated Compose plugin.

Verify it by running:

docker compose version

Expected output:

Docker Compose version v2.x.x

Older installations using docker-compose (with a hyphen) may still function but are no longer the recommended approach for new deployments.

Confirm System Requirements

A complete Wazuh Docker deployment is resource-intensive because it runs multiple services simultaneously.

Before deployment, ensure your server meets or exceeds the recommended hardware requirements:

Modern 64-bit CPU
Multiple CPU cores
SSD storage
Adequate RAM
Stable network connectivity

Production environments generally require significantly more resources than testing environments.

Expert Insight: The Wazuh documentation recommends allocating sufficient CPU and memory to OpenSearch, as the Indexer is typically the most resource-intensive component in the stack. Under-provisioned hosts are one of the leading causes of unstable Docker deployments.

Check Available RAM

Memory shortages frequently cause:

Restart loops
JVM crashes
Slow Dashboard performance
Cluster instability

Check available memory:

free -h

docker stats

If the system is already under heavy memory pressure, consider increasing RAM or adjusting the OpenSearch heap size before continuing.

Verify Available Disk Space

The Indexer stores alert data on disk, making free storage essential.

Check disk utilization:

df -h

Also inspect Docker storage:

docker system df

If disk usage exceeds 85–90%, clean unused images, containers, and volumes before redeploying.

Ensure Required Ports Are Available

Verify that required ports are not already occupied by other applications.

Common ports include:

Service	Port
Dashboard	443 or 5601
Indexer	9200
Indexer Cluster	9300
Manager Agent	1514
Agent Registration	1515
API	55000

To check:

sudo ss -tulpn

sudo netstat -tulpn

Port conflicts prevent containers from starting successfully.

Download the Official Compose Files

Whenever possible, deploy using the official Docker Compose files provided by the Wazuh project rather than third-party examples.

Official deployment files are maintained alongside each Wazuh release and receive updates for new features, bug fixes, and configuration changes.

Using outdated Compose files with newer container images is a common source of deployment failures.

Step 1: Check Container Status

Once the prerequisites have been verified, the first troubleshooting step is determining which containers are healthy and which ones have failed.

Docker provides several commands that quickly reveal the overall health of your deployment.

List Running Containers

Display all running containers:

docker ps

Example:

CONTAINER ID   NAME               STATUS
123abc         wazuh-manager      Up 5 minutes
456def         wazuh-dashboard    Up 5 minutes
789ghi         wazuh-indexer      Up 5 minutes

If expected containers are missing, list every container—including stopped ones:

docker ps -a

Identify Failed Containers

Look for containers whose status shows:

Exited
Restarting
Created
Dead

For example:

wazuh-indexer   Exited (1)

Restarting (1)

These containers should be investigated first because other services often depend on them.

Check Restart Counts

Restart loops usually indicate startup failures.

Inspect restart information:

docker inspect wazuh-manager

docker ps --format "table {{.Names}}\t{{.Status}}"

Repeated restarts generally indicate:

Configuration errors
Missing certificates
Resource exhaustion
Dependency failures

Inspect Exit Codes

Exit codes often provide valuable clues.

View detailed information:

docker inspect wazuh-manager

Common exit codes include:

Exit Code	Meaning
0	Normal shutdown
1	General application error
125	Docker execution failure
126	Permission problem
127	Command not found
137	Killed (usually out of memory)
143	Graceful termination

Exit code 137, in particular, often points to insufficient memory.

Step 2: Review Container Logs

If a container fails during startup, its logs almost always reveal the root cause.

Rather than restarting containers repeatedly, inspect their logs carefully and identify the first error that occurs during initialization.

View Wazuh Manager Logs

Display the Manager logs:

docker logs wazuh-manager

For live monitoring:

docker logs -f wazuh-manager

Look for:

XML parsing failures
Missing configuration files
Certificate problems
API startup failures
Database connection issues

View Wazuh Indexer Logs

Inspect the Indexer:

docker logs wazuh-indexer

Common issues include:

JVM memory errors
Cluster formation failures
Disk watermark warnings
Authentication failures
Certificate validation errors

View Dashboard Logs

Inspect Dashboard startup:

docker logs wazuh-dashboard

Typical problems include:

Unable to reach Indexer
Invalid credentials
Plugin initialization failures
TLS errors
Dashboard configuration problems

View Filebeat Logs

Check Filebeat:

docker logs wazuh-filebeat

Common errors include:

Connection refused
SSL handshake failures
Authentication failures
Failed event publishing

Identify Startup Exceptions

Focus on the earliest fatal exception rather than secondary errors.

Examples include:

Java stack traces
Fatal configuration exceptions
Missing files
Permission denied
Service initialization failures

Many later log entries are simply consequences of the original failure.

Search for Certificate Errors

Certificate problems are among the most common deployment issues.

Look for messages such as:

certificate verify failed
SSL handshake failed
unable to load certificate
x509 validation failed

These usually indicate expired certificates, incorrect file paths, or mismatched certificate authorities.

Related Guide:

How to Fix Wazuh Certificate Errors

Detect Configuration Parsing Errors

Configuration syntax errors often prevent services from starting.

Watch for messages involving:

Invalid YAML
Invalid XML
Unknown settings
Duplicate configuration entries
Missing environment variables

Correcting these parsing errors typically allows the container to start normally.

Step 3: Validate the Docker Compose Configuration

A significant percentage of deployment failures originate in the docker-compose.yml file itself.

Even small mistakes in service definitions, environment variables, volume mappings, or resource limits can prevent containers from communicating correctly.

Before rebuilding your deployment, carefully review the Compose configuration.

Inspect docker-compose.yml

Begin by validating the syntax:

docker compose config

This command checks for:

YAML syntax errors
Invalid references
Missing variables
Incorrect indentation

Fix any reported errors before continuing.

Verify Service Names

Docker networking relies on service names for internal communication.

Ensure services use consistent names throughout the configuration, for example:

manager
indexer
dashboard
filebeat

Changing service names without updating dependent configurations often breaks internal DNS resolution.

Validate Environment Variables

Review every environment variable for accuracy.

Pay particular attention to:

Passwords
API credentials
Hostnames
SSL settings
Cluster names
Memory options

Missing or incorrect variables frequently cause authentication failures or startup errors.

Check Mounted Volumes

Verify that every host directory exists and is mounted correctly.

Common volume locations include:

Configuration files
Certificates
OpenSearch data
Manager data
Dashboard configuration

Incorrect mount paths often result in missing configuration files or startup failures.

Verify Port Mappings

Confirm each published port matches the intended service.

Example:

ports:
  - "443:5601"

Also verify that no other applications are already using those ports.

Confirm Network Definitions

Every Wazuh container should belong to the same Docker network unless your deployment intentionally separates services.

Review:

networks:
  default:

or custom bridge network definitions to ensure containers can communicate.

Validate Resource Limits

Review memory and CPU allocations.

Pay particular attention to:

JVM heap size
Docker memory limits
CPU reservations
Swap settings

Restrictive limits can cause intermittent crashes that appear unrelated to configuration.

Step 4: Verify Docker Networking

Because every Wazuh component communicates over Docker’s virtual network, networking problems often produce cascading failures throughout the deployment.

If containers cannot resolve one another or establish TCP connections, the stack will never become fully operational.

List Docker Networks

Display available networks:

docker network ls

Example:

NETWORK ID      NAME
abc123          bridge
def456          wazuh_default

Locate the network created for your Wazuh deployment.

Confirm All Containers Share the Same Network

Inspect the network:

docker network inspect wazuh_default

Verify that the Manager, Dashboard, Indexer, and Filebeat containers all appear in the attached container list.

If a container is missing, it cannot communicate with the rest of the deployment.

Test DNS Resolution Between Containers

Docker provides automatic DNS resolution based on service names.

From one container, test name resolution:

docker exec -it wazuh-dashboard ping wazuh-indexer

docker exec -it wazuh-dashboard getent hosts wazuh-indexer

Successful resolution confirms that Docker’s internal DNS is functioning correctly.

Verify Container IP Connectivity

Next, verify basic network connectivity.

For example:

docker exec -it wazuh-dashboard curl https://wazuh-indexer:9200

docker exec -it wazuh-manager ping wazuh-indexer

If connectivity fails despite successful DNS resolution, inspect firewall rules, network policies, or custom bridge configurations.

Check Firewall Rules

Finally, verify that neither the host firewall nor external security controls are blocking required traffic.

Review:

UFW rules
firewalld configuration
iptables rules
Cloud security groups (if applicable)

Although containers communicate over an internal Docker network, published ports still rely on the host’s firewall configuration for external access.

Expert Insight: Docker’s networking documentation notes that service discovery within a Compose application relies on an embedded DNS server. Avoid using hard-coded container IP addresses, as they may change whenever containers are recreated.

Step 5: Fix Certificate and SSL Problems

TLS certificates secure communication between the Wazuh Manager, Indexer, Dashboard, and Filebeat.

If certificates are missing, expired, or incorrectly configured, containers may start successfully but fail to communicate with one another.

Certificate-related problems commonly produce errors such as:

SSL handshake failed
certificate verify failed
x509: certificate signed by unknown authority
unable to load certificate
authentication failed

Resolving certificate issues is often enough to restore a broken deployment.

Verify Certificate Files Exist

First, confirm that all required certificate files are present inside the mounted certificate directory.

For example:

ls -la config/wazuh_indexer_ssl_certs/

Depending on your deployment, you should see files similar to:

Root CA certificate
Node certificate
Private key
Admin certificate
Dashboard certificate

If any required file is missing, the affected service may fail during startup.

Check Certificate Permissions

Incorrect file permissions frequently prevent services from reading certificate files.

Inspect permissions:

ls -l config/wazuh_indexer_ssl_certs/

Verify that:

Certificate files are readable.
Private keys are protected but accessible to the appropriate service.
Docker containers have permission to access mounted directories.

Permission-denied errors in container logs usually indicate incorrect ownership or restrictive filesystem permissions.

Validate Certificate Paths

Next, verify that every service references the correct certificate location.

For example, confirm that your configuration points to existing files instead of outdated or renamed paths.

Common issues include:

Incorrect mount locations
Typographical errors
Relative path mistakes
Missing directories after upgrades

Container logs often reveal the exact file path that could not be located.

Confirm Matching Private Keys

Every certificate must correspond to its matching private key.

If certificates and keys become mixed during manual updates, TLS authentication will fail even though both files exist.

Symptoms include:

SSL handshake failures
Authentication errors
Services refusing secure connections

If you recently replaced certificates manually, verify that each certificate matches its intended key pair.

Regenerate Certificates if Necessary

If certificates are corrupted, expired, or cannot be validated, regenerate them using the official Wazuh certificate generation process.

After generating new certificates:

Replace the existing certificate files.
Restart the affected containers.
Confirm successful TLS communication.
Review container logs for remaining SSL errors.

Avoid copying certificates from unrelated deployments, as hostnames and certificate authorities may not match.

Expert Insight: The Wazuh documentation recommends generating certificates specifically for each deployment and ensuring that every node trusts the same certificate authority. Reusing certificates from older installations often leads to trust validation failures.

Step 6: Resolve Persistent Volume Issues

Docker volumes store the persistent data required by Wazuh.

If volumes become corrupted or inaccessible, containers may repeatedly fail during startup or lose important configuration and indexed data.

Before deleting any volume, determine whether it contains production data that should be backed up.

Inspect Docker Volumes

List all Docker volumes:

docker volume ls

Inspect a specific volume:

docker volume inspect wazuh-indexer-data

Verify that:

The volume exists.
The mount point is valid.
Docker recognizes the volume correctly.

Unexpected or missing volumes often indicate deployment configuration problems.

Verify File Ownership

Incorrect ownership is a common cause of startup failures.

Check ownership on mounted directories:

ls -lah

sudo chown -R <user>:<group> <directory>

Ensure that the user running each container can access the mounted files.

Check Permission Problems

Review directory permissions carefully.

Look for:

Read-only directories
SELinux restrictions
Missing execute permissions
Incorrect UID/GID mappings

Permission-related errors commonly appear as:

Permission denied
Unable to create directory
Failed to write data
Read-only filesystem

Remove Corrupted Volumes

If a volume becomes corrupted and contains no critical production data, removing it may be the quickest solution.

Stop the deployment first:

docker compose down

Then remove the affected volume:

docker volume rm <volume_name>

Only perform this step after confirming that important data has been backed up.

Recreate Persistent Storage

After removing corrupted storage, recreate the deployment:

docker compose up -d

Docker automatically creates any missing named volumes defined in the Compose file.

After recreation, verify that all containers initialize successfully and that data is written to the new storage location.

Step 7: Verify Wazuh Indexer Health

The Wazuh Indexer is responsible for storing and retrieving security events.

If it is unhealthy, the Dashboard cannot display alerts, searches fail, and other services may report connection errors.

Always verify Indexer health before troubleshooting higher-level components.

Confirm Indexer Starts Successfully

Begin by confirming that the Indexer container remains running:

docker ps

Its status should remain Up rather than repeatedly restarting or exiting.

If the container stops shortly after startup, review its logs before attempting additional troubleshooting.

Check Cluster Health

Use the OpenSearch Cluster Health API:

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

Healthy clusters generally report:

{
  "status": "green"
}

A yellow status indicates reduced redundancy, while red means the cluster cannot fully access its indexed data.

Review OpenSearch Logs

Inspect Indexer logs:

docker logs wazuh-indexer

Look for messages involving:

Shard allocation failures
JVM exceptions
Authentication errors
Certificate validation
Cluster formation failures
Disk watermark warnings

The earliest fatal error is usually the root cause.

Resolve Memory Lock Errors

Some deployments produce memory lock warnings similar to:

Unable to lock JVM Memory

These warnings typically result from:

Missing memlock settings
Host operating system restrictions
Docker resource configuration

Verify that the Compose configuration matches the recommendations provided by the official deployment documentation.

Verify Java Heap Configuration

The Indexer relies heavily on JVM heap memory.

Review heap settings:

echo $OPENSEARCH_JAVA_OPTS

Typical production deployments allocate approximately half of available system memory to the JVM while leaving sufficient memory for the operating system and other Wazuh services.

Avoid configuring heap sizes larger than necessary, as excessive allocations can reduce overall system performance.

Expert Insight: OpenSearch recommends setting the minimum and maximum heap sizes to the same value and avoiding allocations greater than approximately 50% of available RAM. Oversized heaps can actually increase garbage collection pauses rather than improve performance.

Step 8: Restore Dashboard Connectivity

Once the Manager and Indexer are healthy, focus on restoring communication with the Wazuh Dashboard.

Most Dashboard problems are caused by connectivity, authentication, or configuration issues rather than failures within the web interface itself.

Verify Dashboard Configuration

Review the Dashboard configuration files and verify:

Indexer hostname
Port numbers
TLS settings
Certificate locations
Authentication configuration

Incorrect hostnames are among the most common causes of Dashboard startup failures.

Test Indexer Connectivity

From inside the Dashboard container, verify communication with the Indexer.

For example:

docker exec -it wazuh-dashboard curl -k https://wazuh-indexer:9200

Successful responses confirm that networking and TLS communication are functioning correctly.

If the request times out or fails, investigate Docker networking before modifying Dashboard settings.

Validate Authentication Credentials

Confirm that:

Username
Password
API credentials
Certificates

match those configured on the Indexer.

Authentication failures commonly appear in Dashboard logs immediately after startup.

Fix API Connection Errors

The Dashboard communicates with multiple backend services.

Review log entries for errors involving:

Authentication failures
Connection refused
SSL validation
API unavailable
Timeout exceptions

Correcting the first reported backend error often resolves several secondary failures simultaneously.

Clear Cached Dashboard Data

If configuration changes have been applied but the Dashboard continues to behave unexpectedly, restart the Dashboard container and clear any cached application data where appropriate.

After restarting, monitor logs to confirm successful initialization and verify that the Dashboard loads without connection errors.

Step 9: Resolve Resource Constraints

Resource shortages are among the leading causes of unstable Wazuh Docker deployments.

Since multiple services compete for CPU, memory, storage, and I/O resources, even modest hardware limitations can trigger restart loops, slow indexing, or failed health checks.

Monitoring host resource utilization should be part of every troubleshooting session.

Check CPU Usage

View live container CPU utilization:

docker stats

Also inspect host-level CPU usage:

top

htop

Sustained CPU utilization near 100% may delay indexing, increase response times, or prevent services from completing startup.

Check Memory Consumption

Monitor memory usage:

docker stats

Pay particular attention to:

Wazuh Indexer
Dashboard
Manager

Memory exhaustion frequently results in:

Exit code 137
JVM crashes
Container restarts
Slow Dashboard performance

Verify Disk Utilization

Storage shortages affect indexing performance and cluster stability.

Check available disk space:

df -h

Also review Docker storage:

docker system df

If disk usage approaches capacity, remove unused images, containers, and volumes before expanding storage if necessary.

Increase Docker Memory Limits

If Docker resource limits are too restrictive, adjust the Compose configuration to provide additional memory.

After modifying resource allocations:

Save the Compose file.
Restart the deployment.
Verify that containers remain healthy.
Continue monitoring resource usage.

Increasing memory limits without monitoring actual utilization may only mask underlying configuration problems, so validate the improvement after making changes.

Tune JVM Heap Settings

The OpenSearch JVM heap should be sized according to available system memory.

Review:

Initial heap size
Maximum heap size
Garbage collection behavior

Heap settings that are too small reduce indexing performance, while excessively large heaps increase garbage collection overhead and overall memory pressure.

After adjusting heap settings, restart the Indexer and monitor logs to confirm stable operation.

Expert Insight: Multiple OpenSearch performance guides emphasize monitoring JVM heap utilization over time instead of selecting arbitrary values. A sustained heap utilization of around 75% is generally healthier than operating constantly near maximum capacity.

Step 10: Verify Version Compatibility

Version mismatches are a surprisingly common cause of Docker Compose deployment failures.

Since the Wazuh platform consists of several tightly integrated services, all major components should run compatible releases.

Running different versions of the Manager, Indexer, Dashboard, or Filebeat can lead to authentication failures, unsupported APIs, plugin incompatibilities, and startup errors.

Before troubleshooting individual services, verify that every container is using the intended release.

Match Image Versions

Begin by checking the image tags defined in your docker-compose.yml file.

For example:

image: wazuh/wazuh-manager:4.13.0

Ensure that all Wazuh components reference the same release series whenever possible.

Avoid mixing versions such as:

Manager 4.13
Dashboard 4.12
Indexer 4.11

unless the release documentation explicitly supports that combination.

Check Docker Compose File Version

Official Docker Compose files evolve alongside Wazuh releases.

If you’re deploying newer container images with an older Compose configuration, the deployment may contain:

Missing environment variables
Deprecated configuration options
Incorrect volume mappings
Obsolete health checks

Compare your Compose file with the latest version provided by the Wazuh project before troubleshooting further.

Verify Wazuh Release Compatibility

Review the release notes for the version you’re deploying.

Pay particular attention to:

Breaking changes
Upgrade requirements
Deprecated features
Plugin compatibility
Configuration changes

Some upgrades require manual migration steps that cannot be handled automatically by Docker Compose.

Upgrade Containers Safely

When upgrading:

Back up important data.
Review the release notes.
Pull the updated images.
Upgrade all related components together.
Verify cluster health after deployment.

Avoid upgrading only a single container unless the documentation specifically supports partial upgrades.

Expert Insight: The Wazuh documentation recommends keeping the Manager, Dashboard, and Indexer on the same supported release to minimize compatibility issues during upgrades.

Related Guide:

How to Upgrade a Wazuh Agent

Step 11: Recreate the Deployment

If configuration changes, certificate repairs, and resource adjustments do not resolve the issue, rebuilding the Docker Compose deployment from a clean state is often the fastest solution.

This process removes stale containers, rebuilds networking, and downloads fresh images while allowing you to preserve persistent data when appropriate.

Stop Running Containers

Gracefully stop the deployment:

docker compose down

This stops all containers while preserving named volumes unless additional flags are used.

Remove Containers

If containers remain after shutdown, remove them:

docker container prune

or manually remove individual containers:

docker rm <container_name>

Removing unused containers eliminates stale metadata that may interfere with redeployment.

Remove Networks

Docker Compose automatically creates project-specific networks.

If networking problems persist, remove unused networks:

docker network prune

Alternatively, delete only the Wazuh network if you want to avoid affecting unrelated Docker applications.

Remove Volumes (When Appropriate)

Volumes should only be removed if:

Data corruption is suspected.
The deployment is disposable.
A backup already exists.

To remove volumes:

docker compose down -v

Warning: This command permanently deletes the named volumes associated with the deployment and may erase indexed security events and configuration data.

Pull Fresh Images

Download the latest images referenced in the Compose file:

docker compose pull

This ensures that corrupted or incomplete image layers are replaced before rebuilding the stack.

Deploy the Stack Again

Recreate the deployment:

docker compose up -d

Docker will:

Create networks
Mount volumes
Start containers
Apply health checks

Allow several minutes for all services to initialize before evaluating the deployment.

Verify Successful Startup

Confirm that every container is healthy:

docker ps

Then verify:

No restart loops
Healthy Indexer cluster
Accessible Dashboard
Successful agent connections
Filebeat forwarding alerts

Review container logs one final time to ensure there are no lingering warnings or fatal errors.

Troubleshooting Specific Error Messages

Certain Docker and Wazuh errors appear repeatedly during deployments.

Understanding what these messages mean can significantly reduce troubleshooting time.

“Connection Refused”

This error indicates that a service attempted to connect to another container that was unavailable or not listening on the expected port.

Common causes include:

Target container stopped
Incorrect hostname
Wrong port
Firewall restrictions
Startup timing issues

Verify that the destination service is running before investigating networking.

“No Living Connections”

This message usually originates from the Dashboard when it cannot communicate with the Wazuh Indexer.

Typical causes include:

Indexer unavailable
TLS failures
Incorrect credentials
Cluster startup problems
Docker networking issues

Begin troubleshooting with the Indexer rather than the Dashboard.

“Certificate Verification Failed”

Certificate validation errors indicate that secure communication could not be established.

Possible causes include:

Expired certificates
Incorrect certificate authority
Hostname mismatch
Wrong certificate path
Corrupted certificate files

Verify both certificate validity and configuration.

“Container Restarting”

Containers that repeatedly restart generally encounter fatal initialization errors.

Investigate:

Startup logs
Configuration syntax
Missing environment variables
Resource exhaustion
Dependency services

Avoid repeatedly restarting the container without first reviewing its logs.

“Bind Address Already in Use”

Docker cannot publish a port that another process is already using.

Identify the conflicting process:

sudo ss -tulpn

Either stop the conflicting application or modify the port mapping in the Compose file.

“Permission Denied”

Permission-related failures often affect:

Mounted volumes
Certificate files
Configuration directories

Verify:

File ownership
Directory permissions
SELinux policies
Docker user permissions

“Out of Memory”

Memory exhaustion typically causes:

Exit code 137
JVM crashes
Slow Indexer performance
Restart loops

Review Docker memory usage before increasing heap sizes or container memory limits.

“Cannot Connect to Docker Daemon”

This error indicates that the Docker daemon is unavailable.

Verify:

docker info

If the daemon is not running, restart the Docker service and confirm that your user has permission to access Docker.

“Health Check Failed”

Docker health checks determine whether a container is functioning correctly.

Health check failures often result from:

Slow startup
Failed dependencies
Network timeouts
Resource exhaustion
Configuration errors

Always inspect the container logs before disabling health checks, as the failure usually points to an underlying issue that should be resolved.

Useful Docker Commands for Wazuh Troubleshooting

When troubleshooting Wazuh deployments, a small collection of Docker commands can quickly reveal the health of the entire stack.

Becoming familiar with these commands will make diagnosing deployment issues significantly easier.

View Running Containers

Display active containers:

docker ps

To include stopped containers:

docker ps -a

This provides an immediate overview of container status.

Inspect Container Details

Display detailed container information:

docker inspect wazuh-manager

Useful information includes:

Exit codes
Environment variables
Mounted volumes
Network configuration
Health status

Follow Container Logs

Monitor logs in real time:

docker logs -f wazuh-manager

Replace the container name as needed to troubleshoot other services.

Following logs during startup often reveals configuration issues immediately.

Restart Individual Services

Restart a single container:

docker restart wazuh-dashboard

This is useful after making configuration changes that affect only one service.

Restart the Entire Stack

Restart all services:

docker compose restart

If configuration changes affect multiple containers, restarting the entire stack ensures that dependent services reconnect correctly.

Execute Commands Inside Containers

Open a shell within a running container:

docker exec -it wazuh-manager bash

This allows you to:

Inspect configuration files
Verify mounted volumes
Test network connectivity
Run diagnostic commands

Check Docker Networks

Display Docker networks:

docker network ls

Inspect a specific network:

docker network inspect wazuh_default

These commands help verify container connectivity and DNS resolution.

Inspect Docker Volumes

List Docker volumes:

docker volume ls

Inspect a specific volume:

docker volume inspect wazuh-indexer-data

These commands confirm that persistent storage exists and is mounted correctly.

Expert Insight: Docker recommends using docker inspect and docker logs as the primary diagnostic tools before modifying containers or rebuilding deployments. These commands often identify configuration errors without requiring destructive troubleshooting steps.