Troubleshooting

Checking Broker Status

You can use rabbitmqctl status to verify whether a broker is running.
Normal output from a running broker without plugins follows this pattern:

  Status of node 'rabbit@xxx' ...
  [{pid,...},
   {running_applications,[{rabbit,"RabbitMQ","3.4.0"},
                          {os_mon,"..."},
                          {sasl,"..."},
                          {mnesia,"..."},
                          {stdlib,"..."},
                          {kernel,"..."},
  {os,"..."},
  {erlang_version,"..."},
  {memory,"..."}}]

This example indicates that no broker is running:

  Status of node 'rabbit@xxx' ...
  Error: unable to connect to node 'rabbit@xxx': nodedown
  diagnostics:
  - nodes and their ports on xxx: [{rabbitmqctl,...}]
  - current node: 'rabbitmqctlxxx@xxx'
  - current node home dir: [...]
  - current node cookie hash: [...]

If the diagnostic line looks like this:

  - nodes and their ports on xxx: [{rabbit,...},{rabbitmqctl,...}]
and the broker log file contains entries similar to
  Connection attempt from disallowed node...
then you should make sure the erlang cookies are the same, e.g. by checking that the cookie hash displayed in the diagnostics is the same as that shown by the broker when it starts up.

A common reason for cookie mismatches when invoking rabbitmqctl against a broker on the same host is that broker and rabbitmqctl were run as different user. Evidence of this comes in the form of a mismatch in the node home dir shown by the broker on startup vs what is displayed in the rabbitmqctl diagnostics.

In the absence of the "Connection attempt from disallowed node..." log entry, check that the Erlang distribution port on which the broker is listening is not blocked by a firewall. The port is shown in the {rabbit,...} part of the "nodes and their ports..." diagnostics line. Try connecting to it with e.g. telnet.

If the "nodes and their ports..." line contains no entry for rabbit then the broker probably isn't running. Check the broker logs for errors.

Server Fails to Start

When the server fails to start, usually a crash dump file erl_crash.dump is created in the directory where the server was started. This can provide very detailed information on the causes of a start up failure, but its analysis requires Erlang expertise.

If you attempt to start another server while a broker is already running, then you will receive an error report. You can confirm whether the broker is already running by checking the status.

If the server fails to start, examine the console output and the log files in the RABBITMQ_LOG_BASE directory. Configuration and permission errors are frequently the cause, e.g. the Mnesia directory cannot be created.

Windows Service fails to Install

If the service fails to install, check the service account has full access permission for RABBITMQ_BASE, RABBITMQ_MNESIA_BASE and RABBITMQ_LOG_BASE directories [XP, Vista].

Windows Service fails to Start

If the service fails to start, make sure the service has been installed.

On starting the service, if the service output reads "The process terminated unexpectedly" instead, then the service did not start correctly. Check that the environment variables are set correctly. The logfiles in RABBITMQ_BASE may also contain useful diagnostic information.

If RABBITMQ_BASE path contains non-ASCII characters, RabbitMQ service may fail to start with the error "RabbitMQ: Erlang machine stopped instantly (distribution name conflict?)". If this is the case, override RABBITMQ_BASE to point to a directory that only has ASCII characters and re-install the service (restarting will not be sufficient).

You receive an error message reading "The handle is invalid" after upgrading the Windows Service

The solution is to uninstall RabbitMQ and Erlang. Then remove all registry keys under HKLM/SOFTWARE/Ericsson/Erlang/ErlSrv, and then install Erlang and RabbitMQ (in that order).

Plugin fails to activate

If a plugin fails to activate, check the output of rabbitmq-plugins list.

Problems with SSL

See SSL troubleshooting.

If the server is not behaving as expected during operation, examine the log files and use the rabbitmqctl commands from the admin guide to obtain further information on the server status.

For problems encountered in the handling of AMQP traffic, the AMQP capture and analysis tool may help in the analysis.

Failing that, it's possible that we've solved the problem for someone else. Try using the search box at the top of our web pages to find site, mailing list and blog information. You might also check our mailing list archives.

If you still can't find a solution to your problem then please post a new message to rabbitmq-discuss@lists.rabbitmq.com (you may have to join the mailing list first). Let us know what you were trying to do, the error you received and relevant entries from the logfile and one of our engineers will help you get it fixed.

If all of the above fails, please tell us about the problem, including the log files under RABBITMQ_LOG_BASE in your report.