Menu

Windows Quirks

We aim to make RabbitMQ a first-class citizen on Windows. However, sometimes there are circumstances beyond our control that can introduce quirky behaviour. This page documents them.

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.

Workarounds

  • Override RABBITMQ_BASE to point to a directory that only has ASCII characters and re-install the 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.

rabbitmqctl displays or parses 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.

Workarounds

  • On recent versions of Windows, issue the command " chcp 65001" before using rabbitmqctl to force the console to use UTF-8. (Beware: on older versions including Windows XP this will cause the console to silently fail to run any batch file at all!) or
  • Avoid using non-ASCII characters in object names or
  • Use the management plugin instead of rabbitmqctl.

Installing as a non-administrator user leaves .erlang.cookie

in the wrong place

This makes it impossible to use CLI tools and cluster nodes.

Workarounds

  • Run the installer as an administrator or
  • Copy the file .erlang.cookie manually from %SystemRoot% or %SystemRoot%\system32\config\systemprofile to %HOMEDRIVE%%HOMEPATH%.

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 RABBITMO_NODENAME with the following value:

[email protected]_CAPS_HOSTNAME

Then, RabbitMQ will continue to use the all-caps hostname and your 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!