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.
Anti-virus and related security software can prevent nodes from accepting or opening network connections, accessing files on disk, and so on. This results in failures that are sporadic and very difficult to reason about.
It is highly recommended that RabbitMQ processes, ports, the Windows service, and node data directory are all excluded from scanning by such tools.
An even better option would to be run RabbitMQ nodes on dedicated hosts with a configured firewall but without any anti-virus software.
To specify a non-standard port to be used for Erlang distribution, do the following:
set DIST_PORT=44556
epmd -names
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:
.\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.
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.
One of these options can be used to mitigate:
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.
One of these options can be used to mitigate:
chcp 65001
before using CLI tools to force the console to use UTF-8 * Where possible, use the management plugin instead of CLI tools.
In case the output from rabbitmqctl and other CLI tools looks like this:
←[1mUsage←[0m rabbitmqctl [--node <node>] [--timeout <timeout>] [--longnames] [--quiet] <command> [<command options>] Available commands: ←[1mHelp←[0m: autocomplete Provides command name autocomplete variants help Displays usage information for a command version Displays CLI tools version
Two possible mitigations are:
For further information, including caveats, see Colored text output in PowerShell console using ANSI / VT100 codes
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.
One of these options can be used to mitigate:
See How CLI Tools Authenticate to Nodes (and Nodes to Each Other in the CLI guide.
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.
Due to how RabbitMQ starts as a Windows service, you can't use a configuration file to set net_ticktime and instead must use an environment variable.
First, log in using the administrative account you used, or will use, to install RabbitMQ and create the %AppData%\RabbitMQ\rabbitmq-env-conf.bat file with the following contents:
@echo off set SERVER_ADDITIONAL_ERL_ARGS=-kernel net_ticktime 120
The above will set net_ticktime to 120 seconds.
If you have not yet installed RabbitMQ, the setting will be picked up during installation.
If you have already installed RabbitMQ, open the "RabbitMQ Command Prompt (sbin dir)" start menu item and run these commands:
.\rabbitmq-service.bat stop .\rabbitmq-service.bat remove .\rabbitmq-service.bat install .\rabbitmq-service.bat start
If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them using GitHub Discussions or our community Discord server.
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!