> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Common issues and solutions for Wazuh Dashboard Plugins with diagnostic procedures

This guide provides solutions to common issues you may encounter with the Wazuh dashboard, along with diagnostic procedures and troubleshooting steps.

## Common Error Messages

### Filter Could Not Be Created

**Error Message**:

```
Filter could not be created because no server API is selected. Make sure a server API is available and choose one in the selector.
```

**Description**: The filter related to the selected server API (`cluster.name` in the alerts case or `wazuh.cluster.name` in the inventories data) cannot be created because the required information is not available. The required data to create the filter is stored in the `clusterInfo` cookie in the client browser.

**Cause**: The cookie is not set or the server API information could not be obtained.

**Solutions**:

1. **Verify a server API is selected** in the selector of the dashboard header
2. **Ensure the server API is online and reachable**:

```bash theme={null}
# Test connectivity
ping <SERVER_API_HOST>

# Test API endpoint
curl -k -u <USERNAME>:<PASSWORD> https://<SERVER_API_HOST>:55000/
```

3. **Check the server API configuration** in `opensearch_dashboards.yml`:

```bash theme={null}
grep -A 10 "wazuh_core.hosts:" /etc/wazuh-dashboard/opensearch_dashboards.yml
```

4. **Confirm the `clusterInfo` cookie is set** in the browser:
   * Open browser developer tools (F12)
   * Navigate to Application/Storage > Cookies
   * Check for `clusterInfo` cookie

5. **Clear browser cookies and cache**, then refresh and reselect the API

### Index Pattern Not Found

**Error Message**:

```
Index pattern [id: index_pattern_id] not found.
```

**Description**: The expected index pattern used as a data source for a view or panel could not be found.

**Cause**: The expected index pattern does not exist, or there are no matching indices.

**Solutions**:

1. **Check if the index pattern exists**:
   * Navigate to **Dashboard Management** > **Index Patterns**
   * Look for the specified index pattern ID or title

2. **Create the index pattern** if missing:
   * Go to **Dashboard Management** > **Index Patterns**
   * Click **Create index pattern**
   * Enter the pattern name (e.g., `wazuh-events*`)
   * Select the time field (`timestamp`)
   * Click **Create**

3. **Verify matching indices exist**:

```bash theme={null}
# Check for indices
curl -X GET "https://localhost:9200/_cat/indices/wazuh-*?v" -u admin:admin -k
```

4. **If no matching indices exist**, check:
   * Data collection is enabled on agents
   * Filebeat/Logstash is running and configured correctly
   * Indexer is receiving data
   * Review server and indexer logs for ingestion issues

5. **Run Health Check** to recreate default index patterns:
   * Navigate to **Management** > **Health Check**
   * Click **Check** to regenerate missing resources

### Server API Not Available

**Error Message**:

```
The server API is not available. Check the connection, ensure the service is running, and verify the API host configuration.
```

**Description**: The dashboard cannot connect with the server API host.

**Possible Causes**:

* Server API host is not reachable from the dashboard host
* Network problem (firewall, routing issue)
* Server API is down or stopped
* Wrong server API host configuration (URL, port, or credentials)

**Solutions**:

1. **Ensure the server API is running**:

```bash theme={null}
sudo systemctl status wazuh-manager

# If stopped, start it
sudo systemctl start wazuh-manager
```

2. **Verify API is responding**:

```bash theme={null}
curl -k -u <USERNAME>:<PASSWORD> https://<SERVER_API_HOST>:55000/
```

3. **Check network connectivity**:

```bash theme={null}
# Test basic connectivity
ping <SERVER_API_HOST>

# Test port connectivity
telnet <SERVER_API_HOST> 55000

# Or use nc
nc -zv <SERVER_API_HOST> 55000
```

4. **Review firewall rules**:

```bash theme={null}
# RHEL/CentOS
sudo firewall-cmd --list-all
sudo firewall-cmd --add-port=55000/tcp --permanent
sudo firewall-cmd --reload

# Ubuntu
sudo ufw status
sudo ufw allow 55000/tcp
```

5. **Verify API configuration** in dashboard:

```bash theme={null}
grep -A 10 "wazuh_core.hosts:" /etc/wazuh-dashboard/opensearch_dashboards.yml
```

6. **Check API credentials**:

```bash theme={null}
# On the manager, verify user exists
sudo /var/ossec/bin/wazuh-authd -P
```

7. **Review API logs** on the manager:

```bash theme={null}
sudo tail -f /var/ossec/logs/api.log
```

### No Server API Selected

**Error Message**:

```
No server API selected. Please choose one from the server API selector.
```

**Description**: The server API host is not selected. The selection is stored in the `currentApi` cookie in the browser.

**Cause**: The `currentApi` cookie is not set or has a falsy value.

**Solutions**:

1. **Select a server API** using the selector in the dashboard header

2. **Verify server API is configured**:
   * Navigate to **Server APIs** management
   * Ensure at least one API is configured and reachable

3. **Check browser cookies**:
   * Open developer tools (F12)
   * Navigate to Application/Storage > Cookies
   * Verify `currentApi` cookie exists

4. **Clear browser cookies and cache**, then refresh and select an API

5. **Verify API configuration** in `opensearch_dashboards.yml`:

```bash theme={null}
grep -A 10 "wazuh_core.hosts:" /etc/wazuh-dashboard/opensearch_dashboards.yml
```

## Connection Issues

### Dashboard Cannot Connect to Indexer

**Symptoms**:

* Dashboard fails to start
* Error: "Unable to connect to OpenSearch"
* Saved objects not loading

**Solutions**:

1. **Verify indexer is running**:

```bash theme={null}
sudo systemctl status wazuh-indexer

# Check indexer health
curl -X GET "https://localhost:9200/_cluster/health?pretty" -u admin:admin -k
```

2. **Check indexer connection settings** in `opensearch_dashboards.yml`:

```yaml theme={null}
opensearch.hosts: ['https://localhost:9200']
opensearch.username: 'admin'
opensearch.password: 'admin'
```

3. **Verify SSL certificates**:

```bash theme={null}
# Check certificate files exist
ls -la /etc/wazuh-dashboard/certs/

# Test SSL connection
openssl s_client -connect localhost:9200 -CAfile /etc/wazuh-dashboard/certs/root-ca.pem
```

4. **Review dashboard logs**:

```bash theme={null}
sudo tail -100 /var/log/wazuh-dashboard/opensearch_dashboards.log | grep -i error
```

5. **Check network connectivity** between dashboard and indexer

### Dashboard Cannot Connect to Wazuh API

**Symptoms**:

* "Wazuh API is not reachable" message
* Agent information not loading
* Health check fails on API connection

**Solutions**:

1. **Verify manager is running**:

```bash theme={null}
sudo systemctl status wazuh-manager
```

2. **Test API manually**:

```bash theme={null}
curl -k -u wazuh-wui:wazuh-wui https://localhost:55000/
```

3. **Check API configuration in dashboard**:

```bash theme={null}
grep -A 10 "wazuh_core.hosts:" /etc/wazuh-dashboard/opensearch_dashboards.yml
```

4. **Verify API credentials**:

```bash theme={null}
# Check API user
sudo cat /usr/share/wazuh-dashboard/data/wazuh/config/wazuh-api.yml
```

5. **Check firewall rules** (see Server API Not Available section)

6. **Review API logs**:

```bash theme={null}
sudo tail -f /var/ossec/logs/api.log
```

## Service Issues

### Dashboard Service Fails to Start

**Symptoms**:

* Service fails immediately after starting
* Service shows as "failed" status

**Solutions**:

1. **Check service status**:

```bash theme={null}
sudo systemctl status wazuh-dashboard
```

2. **Review service logs**:

```bash theme={null}
sudo journalctl -u wazuh-dashboard -n 100 --no-pager
```

3. **Check dashboard logs**:

```bash theme={null}
sudo tail -100 /var/log/wazuh-dashboard/opensearch_dashboards.log
```

4. **Verify configuration syntax**:

```bash theme={null}
# Check for syntax errors
sudo grep -v "^#" /etc/wazuh-dashboard/opensearch_dashboards.yml | grep -v "^$"
```

5. **Check file permissions**:

```bash theme={null}
ls -la /etc/wazuh-dashboard/
ls -la /usr/share/wazuh-dashboard/
```

6. **Verify port availability**:

```bash theme={null}
# Check if port 5601 (or configured port) is available
sudo netstat -tlnp | grep 5601
```

7. **Check disk space**:

```bash theme={null}
df -h
```

### Dashboard Service Crashes

**Symptoms**:

* Service starts but crashes shortly after
* Intermittent service failures

**Solutions**:

1. **Monitor logs in real-time**:

```bash theme={null}
sudo tail -f /var/log/wazuh-dashboard/opensearch_dashboards.log
```

2. **Check for memory issues**:

```bash theme={null}
# Check available memory
free -h

# Check for OOM killer
sudo dmesg | grep -i "out of memory"
```

3. **Increase Node.js memory limit**:

```bash theme={null}
sudo systemctl edit wazuh-dashboard

# Add:
[Service]
Environment="NODE_OPTIONS=--max-old-space-size=4096"
```

4. **Check for plugin conflicts**:

```bash theme={null}
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin list
```

5. **Review system resources**:

```bash theme={null}
top
iostat
vmstat
```

## Authentication and Authorization Issues

### Login Failures

**Symptoms**:

* Unable to log in to dashboard
* "Invalid credentials" errors

**Solutions**:

1. **Verify credentials** with direct indexer access:

```bash theme={null}
curl -X GET "https://localhost:9200/" -u <USERNAME>:<PASSWORD> -k
```

2. **Check authentication configuration**:

```bash theme={null}
grep -i "opensearch.username" /etc/wazuh-dashboard/opensearch_dashboards.yml
```

3. **Reset user password** if needed (on indexer):

```bash theme={null}
# Using OpenSearch security plugin
sudo /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh \
  -cd /usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig/ \
  -icl -nhnv -cacert /etc/wazuh-indexer/certs/root-ca.pem \
  -cert /etc/wazuh-indexer/certs/admin.pem \
  -key /etc/wazuh-indexer/certs/admin-key.pem
```

4. **Check security plugin configuration** on indexer

### Permission Denied Errors

**Symptoms**:

* Actions fail with permission errors
* "Insufficient permissions" messages

**Solutions**:

1. **Verify user roles** in OpenSearch Dashboards:
   * Navigate to **Security** > **Roles**
   * Check user's assigned roles

2. **Review API user permissions**:

```bash theme={null}
# On manager
sudo /var/ossec/bin/wazuh-authd -P
```

3. **Check RBAC configuration** for API access

4. **Verify run\_as setting** in API configuration:

```yaml theme={null}
wazuh_core.hosts:
  default:
    run_as: true  # Should be true for most operations
```

## Data and Display Issues

### No Data Displayed

**Symptoms**:

* Dashboards show "No results found"
* Event tables are empty
* Visualizations show no data

**Solutions**:

1. **Check time range**:
   * Expand time range to include expected data
   * Verify data exists in the selected time period

2. **Verify indices exist and contain data**:

```bash theme={null}
# Check indices
curl -X GET "https://localhost:9200/_cat/indices/wazuh-*?v&s=index" -u admin:admin -k

# Check document count
curl -X GET "https://localhost:9200/wazuh-events*/_count" -u admin:admin -k
```

3. **Check index pattern**:
   * Verify correct index pattern is selected
   * Refresh index pattern field list
   * Recreate index pattern if necessary

4. **Review applied filters**:
   * Clear all filters and retry
   * Check for conflicting filters

5. **Verify agent is sending data**:

```bash theme={null}
# On agent
sudo systemctl status wazuh-agent

# Check agent logs
sudo tail -f /var/ossec/logs/ossec.log
```

### Visualizations Not Loading

**Symptoms**:

* Visualizations show errors or fail to render
* Dashboards partially load

**Solutions**:

1. **Check browser console** for JavaScript errors (F12)

2. **Clear browser cache** and reload

3. **Verify index pattern** is valid and has data

4. **Check visualization queries** for syntax errors

5. **Review dashboard logs**:

```bash theme={null}
sudo tail -100 /var/log/wazuh-dashboard/opensearch_dashboards.log
```

6. **Regenerate visualizations** through Health Check

### Saved Objects Missing

**Symptoms**:

* Dashboards or visualizations disappeared
* Recently created objects not found

**Solutions**:

1. **Check tenant/space** selection (if using multi-tenancy)

2. **Search for objects**:
   * Navigate to **Dashboard Management** > **Saved Objects**
   * Search by name or type

3. **Import from backup** if available

4. **Check indexer for saved objects**:

```bash theme={null}
curl -X GET "https://localhost:9200/.kibana/_search?pretty" -u admin:admin -k
```

5. **Run Health Check** to recreate default objects

## Performance Issues

### Slow Dashboard Performance

**Symptoms**:

* Dashboard loads slowly
* Queries take a long time
* UI is unresponsive

**Solutions**:

1. **Reduce time range** for queries

2. **Apply filters** before loading data

3. **Check system resources**:

```bash theme={null}
top
free -h
df -h
iostat
```

4. **Optimize indexer**:

```bash theme={null}
# Force merge indices
curl -X POST "https://localhost:9200/wazuh-events*/_forcemerge?max_num_segments=1" -u admin:admin -k
```

5. **Review slow queries**:

```bash theme={null}
tail -f /var/log/wazuh-indexer/wazuh_index_search_slowlog.log
```

6. **Increase dashboard timeout**:

```yaml theme={null}
# In opensearch_dashboards.yml
opensearch.requestTimeout: 60000
```

7. **Clear browser cache** and restart browser

See the [Performance Tuning](/guides/performance-tuning) guide for comprehensive optimization strategies.

### High Memory Usage

**Symptoms**:

* Dashboard consumes excessive memory
* System becomes slow
* Out of memory errors

**Solutions**:

1. **Check memory usage**:

```bash theme={null}
free -h
ps aux | grep opensearch-dashboards
```

2. **Increase Node.js memory**:

```bash theme={null}
sudo systemctl edit wazuh-dashboard

# Add:
[Service]
Environment="NODE_OPTIONS=--max-old-space-size=4096"
```

3. **Restart dashboard service**:

```bash theme={null}
sudo systemctl restart wazuh-dashboard
```

4. **Close unnecessary visualizations**

5. **Reduce concurrent queries**

## Plugin Issues

### Plugin Errors

**Symptoms**:

* Plugin fails to load
* Plugin-specific features not working

**Solutions**:

1. **List installed plugins**:

```bash theme={null}
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin list
```

2. **Check plugin compatibility**:

```bash theme={null}
cat /usr/share/wazuh-dashboard/plugins/wazuh/package.json | grep -A 2 "opensearchDashboards"
```

3. **Remove and reinstall plugin**:

```bash theme={null}
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin remove wazuh
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin install <PLUGIN_URL>
```

4. **Clear optimization cache**:

```bash theme={null}
sudo rm -rf /usr/share/wazuh-dashboard/optimize/bundles/*
sudo systemctl restart wazuh-dashboard
```

5. **Check plugin logs** in dashboard logs

## Upgrade and Migration Issues

### Upgrade Failures

**Symptoms**:

* Package upgrade fails
* Service fails after upgrade

**Solutions**:

1. **Check package manager logs**:

```bash theme={null}
# Debian/Ubuntu
sudo cat /var/log/apt/term.log

# RHEL/CentOS
sudo cat /var/log/yum.log
```

2. **Verify package integrity**:

```bash theme={null}
# Debian/Ubuntu
dpkg -l | grep wazuh-dashboard

# RHEL/CentOS
rpm -qa | grep wazuh-dashboard
```

3. **Review upgrade logs**

4. **Check for outdated plugins** (see Plugin Issues)

5. **Restore from backup** if necessary

See the [Upgrade Procedures](/guides/upgrade) guide for detailed upgrade steps.

### Migration Issues

**Symptoms**:

* Configuration not working after migration
* Features missing after migration

**Solutions**:

1. **Review migration guide** for breaking changes

2. **Check configuration migration**:
   * Verify settings moved from `wazuh.yml` to `opensearch_dashboards.yml`
   * Update index patterns
   * Review deprecated settings

3. **Run Health Check** to recreate resources

4. **Import saved objects** from backup

See the [Migration Guide (4.x to 5.x)](/guides/migration-4x-5x) for comprehensive migration steps.

## Diagnostic Commands

### Collect System Information

```bash theme={null}
#!/bin/bash
# Wazuh Dashboard Diagnostic Script

echo "=== System Information ==="
uname -a
cat /etc/os-release

echo "\n=== Dashboard Version ==="
dpkg -l | grep wazuh-dashboard  # Debian/Ubuntu
rpm -qa | grep wazuh-dashboard   # RHEL/CentOS

echo "\n=== Service Status ==="
systemctl status wazuh-dashboard

echo "\n=== Port Status ==="
netstat -tlnp | grep 5601

echo "\n=== Recent Logs ==="
tail -50 /var/log/wazuh-dashboard/opensearch_dashboards.log

echo "\n=== Disk Space ==="
df -h

echo "\n=== Memory Usage ==="
free -h

echo "\n=== Configuration ==="
grep -v "^#" /etc/wazuh-dashboard/opensearch_dashboards.yml | grep -v "^$"

echo "\n=== Installed Plugins ==="
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin list

echo "\n=== Indexer Health ==="
curl -X GET "https://localhost:9200/_cluster/health?pretty" -u admin:admin -k

echo "\n=== API Health ==="
curl -k -u wazuh-wui:wazuh-wui https://localhost:55000/
```

### Export Logs for Support

```bash theme={null}
# Create diagnostic bundle
sudo tar -czf wazuh-dashboard-diagnostics-$(date +%Y%m%d-%H%M%S).tar.gz \
  /var/log/wazuh-dashboard/ \
  /etc/wazuh-dashboard/opensearch_dashboards.yml \
  --exclude=/etc/wazuh-dashboard/certs/*.key
```

> [!WARNING]
>
> Do not include private keys in diagnostic bundles. Exclude certificate keys and password files.

## Getting Help

### Community Support

* **Community forum**: [https://groups.google.com/g/wazuh](https://groups.google.com/g/wazuh)
* **GitHub issues**: [https://github.com/wazuh/wazuh-dashboard-plugins/issues](https://github.com/wazuh/wazuh-dashboard-plugins/issues)
* **Documentation**: [https://documentation.wazuh.com/](https://documentation.wazuh.com/)

### Reporting Issues

When reporting issues, include:

1. **Wazuh version** (dashboard, manager, indexer)
2. **Operating system** and version
3. **Error messages** (complete and unedited)
4. **Relevant logs** (sanitized for sensitive data)
5. **Steps to reproduce** the issue
6. **Expected vs actual behavior**
7. **Recent changes** (upgrades, configuration changes)

### Enterprise Support

For enterprise support options, visit: [https://wazuh.com/professional-services/](https://wazuh.com/professional-services/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.