🚨 RabbitMQ Error Guide: 'Error preparing configuration' — Fix rabbitmq.conf Syntax

Overview

The broker could not parse its configuration at startup, so it failed the config boot step and refused to start:

Error preparing configuration in one of [...]/rabbitmq.conf:
  error, syntax error before: '='  (line 14)

RabbitMQ’s rabbitmq.conf uses the sysctl-style Cuttlefish format (key = value), while advanced.config uses raw Erlang terms. A malformed key, an unknown setting, or a bad Erlang term makes config preparation fail — the node cannot start until the file parses cleanly.

Symptoms

• The node won’t start; logs show Error preparing configuration or a Cuttlefish schema error naming a file and line.
• systemctl status rabbitmq-server shows the unit failing right after start.
• The failure appeared immediately after editing rabbitmq.conf or advanced.config.
• An unknown/renamed setting is reported as not matching any schema mapping.
• advanced.config errors reference a missing period or bad Erlang tuple.

Common Root Causes

• Wrong syntax for the file — using Erlang-tuple syntax in rabbitmq.conf (which expects key = value) or sysctl syntax in advanced.config (which expects Erlang terms).
• Unknown/renamed setting — a key that doesn’t exist in this version’s schema (settings get renamed across versions).
• Missing Erlang period — an advanced.config term not terminated with ..
• Bad value type — a string where a number/atom is expected, or a malformed list.
• Duplicate or conflicting keys — the same setting defined twice with incompatible values.
• Copy-paste artifacts — smart quotes, tabs, or trailing characters that break the parser.

Diagnostic Workflow

Read the exact parse error — it names the file and usually the line:

journalctl -u rabbitmq-server --since '10 min ago' | grep -iA10 'preparing configuration'
grep -iE 'preparing configuration|cuttlefish|schema' /var/log/rabbitmq/*.log | tail

Confirm which config files the node is loading:

rabbitmqctl environment | grep -iE 'config_file|advanced'
ls -l /etc/rabbitmq/rabbitmq.conf /etc/rabbitmq/advanced.config 2>/dev/null

Sanity-check advanced.config as valid Erlang before restarting (it must parse as a term list and end with a period):

erl -noshell -eval \
  'case file:consult("/etc/rabbitmq/advanced.config") of {ok,_}->io:format("OK~n"); E->io:format("~p~n",[E]) end, halt().'

Inspect the offending line for smart quotes, tabs, or wrong syntax:

sed -n '10,18p' /etc/rabbitmq/rabbitmq.conf | cat -A   # cat -A reveals tabs/CRLF

Example Root Cause Analysis

A node stopped starting right after a config change, logging Error preparing configuration ... syntax error before: '{'. The operator had added a listener setting but used advanced.config Erlang-tuple syntax inside rabbitmq.conf:

# rabbitmq.conf (WRONG - Erlang tuple in a Cuttlefish file)
{rabbit, [{tcp_listeners, [5672]}]}.

rabbitmq.conf expects sysctl-style keys. The correct form is:

# rabbitmq.conf (CORRECT)
listeners.tcp.default = 5672

After replacing the tuple with the key = value form and restarting, the config boot step passed and the node started. Root cause: mixing the two config formats — Erlang tuples belong only in advanced.config.

Prevention Best Practices

• Keep rabbitmq.conf in Cuttlefish key = value form; put raw Erlang terms only in advanced.config.
• Validate config changes on a non-production node before rolling them out — a parse error fails boot instantly.
• Version-control config and review diffs; most breakages are a single mistyped or unknown key.
• Check the setting name against the running version’s schema; keys are renamed across releases.
• Strip smart quotes/tabs (cat -A) and end every advanced.config term with a period.

Quick Command Reference

grep 'preparing configuration' /var/log/rabbitmq/*.log       # the parse error + line
rabbitmqctl environment | grep -i config_file                # which files load
erl -noshell -eval 'file:consult("/etc/rabbitmq/advanced.config").' -s init stop  # validate Erlang
sed -n '1,40p' /etc/rabbitmq/rabbitmq.conf | cat -A          # reveal hidden chars

Conclusion

Error preparing configuration means RabbitMQ couldn’t parse a config file and aborted the config boot step. The error names the file and line — check first that you used the right syntax for the right file (key = value in rabbitmq.conf, Erlang terms ending in . in advanced.config), that the key exists in this version’s schema, and that no smart quotes or tabs crept in. Validate config on a staging node before restart so a one-character typo never takes a broker offline.