Troubleshooting

This section contains common issues that might occur when upgrading the Wazuh central components and provides steps to resolve them.

Wazuh-DB backup restoration

Wazuh by default performs automatic backups of the global.db database. These snapshots may be useful to recover critical information such as agent keys, agent synchronization information, and FIM event data among others. Wazuh-DB will restore the last backup available in case of failure during the upgrade. If this process also fails, the restoration must be done manually.

Manual restoration process

  1. Stop the Wazuh manager.

    # systemctl stop wazuh-manager
    
  2. Locate the backup to restore. It is stored in /var/ossec/backup/db/ with a name format similar to global.db-backup-TIMESTAMP-pre_upgrade.gz.

    Note

    This process is valid for all the backups in the folder. Snapshot names containing the special tag pre_upgrade were created right before upgrading the Wazuh server. Any other snapshot is a periodic backup created according to the backup setting.

  3. Decompress the backup file. Always use the -k flag to preserve the original file:

    # gzip -dk WAZUH_HOME/backup/db/global.db-backup-TIMESTAMP-pre_upgrade.gz
    
  4. Remove the current global.db database and move the backup to the right location:

    # rm  WAZUH_HOME/queue/db/global.db
    # mv  WAZUH_HOME/backup/db/global.db-backup-TIMESTAMP-pre_upgrade WAZUH_HOME/queue/db/global.db
    
  5. Start the Wazuh manager.

    # systemctl start wazuh-manager
    

Wazuh dashboard server is not ready yet

This message typically appears right after starting or restarting the Wazuh dashboard. However, it may also indicate one of the following issues:

  • The Wazuh dashboard service is encountering an error and repeatedly restarting.

  • The Wazuh dashboard cannot communicate with the Wazuh indexer.

  • The Wazuh indexer service is not running or has encountered an error.

Steps to diagnose and fix the issue

  1. Ensure the Wazuh dashboard service is active. Run the following command on the Wazuh dashboard node to check the status:

    # systemctl status wazuh-dashboard
    
  2. Check the Wazuh dashboard logs for errors. Run the following command on the Wazuh dashboard node:

    # journalctl -u wazuh-dashboard | grep -i -E "error|warn"
    
  3. Ensure the Wazuh dashboard is correctly configured to communicate with the Wazuh indexer. Open the dashboard /etc/wazuh-dashboard/opensearch_dashboards.yml file and verify the Wazuh indexer IP address configured in the opensearch.hosts field:

    opensearch.hosts: https://<WAZUH_INDEXER_IP_ADDRESS>:9200
    
  4. Check the connectivity between the Wazuh dashboard and the Wazuh indexer. Replace <WAZUH_INDEXER_IP_ADDRESS> and run the following command on the Wazuh dashboard node:

    # curl -v telnet://<WAZUH_INDEXER_IP_ADDRESS>:9200
    
  5. Ensure the Wazuh indexer service is active. Run the following command on the Wazuh indexer node to check the status:

    # systemctl status wazuh-indexer
    

    If the service is down, investigate potential errors.

  6. Replace <WAZUH_INDEXER_CLUSTER_NAME> and run the following command on the Wazuh indexer node to check the indexer logs for errors:

    # cat /var/log/wazuh-indexer/<WAZUH_INDEXER_CLUSTER_NAME>.log | grep -E "ERROR|WARN|Caused"
    

The 'vulnerability-detector' configuration is deprecated

This warning occurs because upgrading the Wazuh manager does not modify the /var/ossec/etc/ossec.conf file, preserving the previous Wazuh Vulnerability Detection module configuration. Additionally, warnings about invalid configurations for interval, min_full_scan_interval, run_on_start and provider elements may appear. To resolve these issues, update the configuration as outlined in Configuring vulnerability detection.

No username and password found in the keystore

To ensure alerts and vulnerabilities are indexed and displayed on the Wazuh dashboard, add indexer credentials to the manager keystore.

Run the following commands to store the credentials securely:

# echo '<INDEXER_USERNAME>' | /var/ossec/bin/wazuh-keystore -f indexer -k username
# echo '<INDEXER_PASSWORD>' | /var/ossec/bin/wazuh-keystore -f indexer -k password

If you've forgotten your Wazuh indexer password, refer to the password management guide to reset it.

IndexerConnector initialization failed

This warning may indicate incorrect keystore credentials, a configuration issue, or a certificate error. Verify that the IP address, port, and certificate paths are correctly configured in the <indexer> section of /var/ossec/etc/ossec.conf.

After resolving the issue and successfully connecting the Wazuh manager to the indexer, you should see a log like this:

INFO: IndexerConnector initialized successfully for index: ...

If the error persists, enable wazuh_modules.debug=2 temporarily in /var/ossec/etc/local_internal_options.conf for more details.

Vulnerability detection seems to be disabled or has a problem

This warning suggests that the Wazuh Vulnerability Detection module might be disabled or misconfigured. To troubleshoot, follow these steps:

  1. Ensure the vulnerability-detection module is enabled in /var/ossec/etc/ossec.conf.

  2. Locate the <indexer> block in /var/ossec/etc/ossec.conf and confirm there are no misconfigurations or duplicate <indexer> sections.

  3. Verify the wazuh-states-vulnerabilities-* index is correctly created. Ensure it is present and its health status is green by navigating to Indexer Management > Index Management > Indexes on the Wazuh dashboard.

  4. If the index wasn’t created, check the Wazuh manager logs for errors or warnings using the following command:

    # cat /var/ossec/logs/ossec.log | grep -i -E "error|warn"
    

Application Not Found

If you see the message Application Not Found when accessing the Wazuh dashboard after upgrading, it may be because the configuration file /etc/wazuh-dashboard/opensearch_dashboards.yml wasn’t updated with the latest changes.

To fix this issue, update the uiSettings.overrides.defaultRoute setting in the /etc/wazuh-dashboard/opensearch_dashboards.yml file to the following value:

uiSettings.overrides.defaultRoute: /app/wz-home

SSO issue when upgrading from Wazuh 4.8 and earlier

If upgrading from Wazuh 4.8 or earlier, update the exchange_key value in /etc/wazuh-indexer/opensearch-security/config.yml.

Previously, exchange_key was set by copying the X.509 Certificate blob, excluding the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

Starting with Wazuh 4.9.0, exchange_key must be a 64-character random alphanumeric string.

For guidance, refer to the first step of the Wazuh indexer configuration in the Single sign-on (SSO) guides for platforms like Okta, Microsoft Entra ID, PingOne, Google, Jumpcloud, OneLogin, and Keycloack.

None of the above solutions are fixing my problem

We have a welcoming community ready to assist with most Wazuh deployment and usage issues. Visit any of the Wazuh community channels for support.

You can also report issues directly on our GitHub repositories under the Wazuh organization.

When reporting a problem, include detailed information such as the version, operating system, and relevant logs to help us assist you effectively.