Menu

Windows-specific Issues

This guide is a companion to the main Windows installation guide.

It documents known conditions and scenarios which can cause RabbitMQ Windows service or CLI tools to malfunction.

Erlang Distribution Port

To specify a non-standard port to be used for Erlang distribution, do the following:

  • Make sure to use the same administrative user that was used to install RabbitMQ
  • Stop the RabbitMQ Windows service using .\rabbitmq-service.bat stop
  • Remove the RabbitMQ Windows service using .\rabbitmq-service.bat remove
  • Create the %AppData%\RabbitMQ\rabbitmq-env-conf.bat file with the following contents (use your own port number):
set DIST_PORT=44556
  • Install the RabbitMQ Windows service using .\rabbitmq-service.bat install
  • Start the RabbitMQ Windows service using .\rabbitmq-service.bat start
  • Verify what port is being used for inter-node and CLI tool communication:
epmd -names

Multiple Versions of Erlang May Cause Installation Issues

Due to how the Windows .exe installer detects an installed version of Erlang, RabbitMQ may end up not using the latest version of Erlang installed. Please ensure that only one version of Erlang is installed - the version you wish RabbitMQ to use. If you must upgrade Erlang, use this procedure:

  • Make sure to use the same administrative user that was used to install RabbitMQ
  • Stop the RabbitMQ Windows service using .\rabbitmq-service.bat stop
  • Uninstall Erlang
  • Install the new version of Erlang
  • Open the "RabbitMQ Command Prompt (sbin dir)" start menu item and run the commands below to reinstall the Windows service
.\rabbitmq-service.bat remove
.\rabbitmq-service.bat install
.\rabbitmq-service.bat start

If any environment variables have changed in the mean time, Windows service reinstallation would also be necessary.

Cannot Install to a Path with non-ASCII Characters

RabbitMQ will fail to start with the error that reads

RabbitMQ: Erlang machine stopped instantly (distribution name conflict?)

when installed to a path with non-ASCII characters in it. This is because we need to pass the location of the compiled Erlang files to the Erlang VM. It expects input in UTF-8, but the console will typically use some other encoding.

Mitigation

One of these options can be used to mitigate:

  • Override RABBITMQ_BASE to point to a directory that only has ASCII characters and re-install the Windows service.
  • Edit the file rabbitmq-server.bat and change the line set TDP0=%~dp0 to set TDP0=%~dps0. This will use short paths (the infamous C:\PROGRA~1) everywhere.

CLI Tools Display or Parse non-ASCII Characters Incorrectly

Similarly, RabbitMQ CLI tools will expect command line parameters to be encoded in UTF-8, and display strings as UTF-8. The console will instead provide and expect some country-specific encoding.

Mitigation

One of these options can be used to mitigate:

  • Avoid using non-ASCII characters in RabbitMQ installation and node directory paths
  • On recent versions of Windows, issue the command 
    chcp 65001
    before using CLI tools to force the console to use UTF-8
  • Where possible, use the management plugin instead of CLI tools.

Installing as a non-administrator User Leaves .erlang.cookie in the Wrong Place

If RabbitMQ is installed using a non-administrative account, a shared secret file used by nodes and CLI tools will not be placed into a correct location, leading to authentication failures when rabbitmqctl.bat and other CLI tools are used.

Mitigation

One of these options can be used to mitigate:

  • Re-install RabbitMQ using an administrative user
  • Copy the file .erlang.cookie manually from %SystemRoot% or %SystemRoot%\system32\config\systemprofile to %HOMEDRIVE%%HOMEPATH%.

See How CLI Tools Authenticate to Nodes (and Nodes to Each Other in the CLI guide.

COMPUTERNAME is different from HOSTNAME

Older versions of RabbitMQ calculated the node name using the COMPUTERNAME environment variable, which is always upper-case. Later versions of RabbitMQ use HOSTNAME which may be lowercase. If you are upgrading from an old (pre-3.6.0) version of RabbitMQ to a current one and see the issue described here, you should set a system-wide environment variable named RABBITMQ_NODENAME with the following value: rabbit@ALL_CAPS_HOSTNAME.

Then, RabbitMQ will continue to use the all-caps hostname and the upgrade will succeed.

Getting Help and Providing Feedback

If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.

Help Us Improve the Docs <3

If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!