Diagnostic Mode

HiveMQ provides a Diagnostic Mode that collects detailed information about the system on which HiveMQ runs. This fine-grained data helps our support team analyze and resolve issues specific to your installation.

The diagnostic mode is disabled by default. Only enable this mode when actively troubleshooting an issue with your installation. While the diagnostic mode is enabled, performance decreases significantly and HiveMQ writes large amounts of data to disk. Diagnostic mode is not intended for normal production operation.

Enabling Diagnostic Mode

To enable the diagnostic mode, modify the startup script located in your HiveMQ bin directory.

Uncomment the following lines in the run.sh file for Linux systems or the run.bat file for Windows systems as follows:

Enable diagnostic mode for Linux
# Uncomment for enabling Diagnostic Mode
JAVA_OPTS="$JAVA_OPTS -DdiagnosticMode=true"
Enable diagnostic mode for Windows
rem Uncomment for enabling diagnostic mode
set "JAVA_OPTS=-DdiagnosticMode=true %JAVA_OPTS%"

When Diagnostic Mode is successfully enabled, the HiveMQ log includes a message similar to the following statement:

+ 2026-01-25 12:59:25,669 INFO - Starting with Diagnostic mode

Diagnostic Mode Output

When diagnostic mode starts, HiveMQ creates a diagnostics folder to store all diagnostic information and adds the following files:

File Name Description

diagnostics.txt

Diagnostic information about HiveMQ and the system on which HiveMQ is running.

tracelog.log

A HiveMQ trace log.

Sharing Diagnostics Mode Output with HiveMQ Support

  • Run the diagnostic mode as long as needed to reproduce the issue you want solved.

  • As soon as you reproduce the issue, stop HiveMQ.

  • Review the files HiveMQ created and edit any information that is too sensitive to share with the HiveMQ support team.

  • Send all files in the diagnostics folder to support@hivemq.com with as detailed a description of the issue as possible.

Running diagnostic mode for an extended period can generate extremely large log files.
Only enable diagnostic mode for the minimum time necessary to reproduce the specific issue you are investigating.