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 "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 shows / parses non-ASCII characters incorrectly

Similarly, rabbitmqctl 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 rabbitmqctl.

Workarounds:

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

Shutting down Windows

It is necessary to take precautions when shutting down Windows and using versions of Erlang prior to R15B02. Due to limitations in older versions of the underlying Erlang VM, the broker will not go through a controlled shutdown sequence when Windows shuts down. If RabbitMQ is installed as a service using an older version of Erlang then you must stop the service manually before shutting down Windows. Failure to do so may cause the broker to spend longer on recovery when started subsequently. The use of Erlang R15B02 or later is recommended to avoid this problem.

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.

Documentation feedback is also very welcome on the list. If you'd like to contribute an improvement to the site, its source is available on GitHub.