🚨 RabbitMQ Error Guide: 'BOOT FAILED' — Fix a Broker That Won't Start

Overview

The RabbitMQ node aborted during startup: one of its ordered boot steps raised an error, so the broker printed BOOT FAILED and exited instead of coming up:

BOOT FAILED
===========
Error during startup: {error,
  {rabbit,failed_to_start_child,
    {rabbit_mnesia,{schema_integrity_check_failed,...}}}}

RabbitMQ starts by running a sequence of named boot steps (config load, Mnesia/schema, listeners, plugins). If any step fails, boot halts and the node never reaches a running state — nothing on this node accepts connections until the failing step is fixed.

Symptoms

• The service fails to start; logs end with BOOT FAILED and an Error during startup tuple.
• systemctl status rabbitmq-server shows the unit exited/activating in a loop.
• rabbitmqctl status reports the node is not running.
• The failure names a specific subsystem: rabbit_mnesia, a plugin, a listener, or config parsing.
• The node crashes the same way on every restart until the underlying cause is cleared.

Common Root Causes

• Corrupt or incompatible schema/Mnesia data — an unclean shutdown or a downgrade left the schema in a state this version can’t load.
• Config parse failure — a malformed rabbitmq.conf/advanced.config makes the config boot step fail.
• Feature-flag mismatch — data written after a feature flag was enabled won’t load on a node/version that doesn’t support it.
• Listener bind failure — a port (5672/15672) is already in use, failing the networking boot step.
• Plugin failure — an enabled plugin errors during its own boot step, often after a version mismatch.
• Permissions/disk — the rabbitmq user can’t read/write the data dir, or the disk is full, so a persistence step fails.

Diagnostic Workflow

Read the full startup error — the tuple names the failing boot step, which is the fastest signal:

journalctl -u rabbitmq-server --since '15 min ago' | grep -iA20 'BOOT FAILED'
tail -n 100 /var/log/rabbitmq/rabbit@$(hostname -s).log

Check for a config parse problem specifically:

grep -iE 'error preparing config|cuttlefish|rabbitmq.conf' \
  /var/log/rabbitmq/*.log

Confirm ports aren’t already bound (listener step) and the data dir is healthy:

ss -ltnp | grep -E ':5672|:15672|:25672'
ls -ld /var/lib/rabbitmq/mnesia
df -h /var/lib/rabbitmq

Inspect feature-flag state if the failure mentions schema/feature flags (run on a healthy peer node):

rabbitmqctl list_feature_flags   # from a running node in the cluster

Example Root Cause Analysis

A single node in a 3-node cluster entered a crash loop after a power event, ending every start with BOOT FAILED and rabbit_mnesia,{schema_integrity_check_failed,...}. The other two nodes were healthy.

The log showed the Mnesia boot step failing schema integrity — the unclean shutdown had corrupted this node’s local schema copy. Because the cluster still had a majority of healthy nodes holding the authoritative state, the safe fix was to reset the failed node and let it re-sync from its peers rather than trying to repair the corrupt local files:

systemctl stop rabbitmq-server
rabbitmqctl force_reset            # wipe this node's local schema/data
systemctl start rabbitmq-server
rabbitmqctl join_cluster rabbit@node1   # rejoin, re-sync from healthy peers
rabbitmqctl start_app

The node booted, rejoined, and synced. Root cause: local schema corruption from the unclean stop; recovery leaned on cluster redundancy instead of file surgery.

Prevention Best Practices

• Always stop nodes cleanly (rabbitmqctl stop_app / graceful shutdown) so the schema is left consistent.
• Validate rabbitmq.conf changes on a non-production node; a config parse error fails boot instantly.
• Upgrade the whole cluster before enabling irreversible feature flags, and never downgrade a node past data written with a newer flag.
• Keep definitions exported so a reset-and-rejoin node can be restored declaratively.
• Monitor disk on the data volume; a full disk fails persistence boot steps.

Quick Command Reference

journalctl -u rabbitmq-server | grep -iA20 'BOOT FAILED'   # the failing boot step
tail -n 100 /var/log/rabbitmq/rabbit@$(hostname -s).log
ss -ltnp | grep -E ':5672|:25672'          # listener/port conflicts
df -h /var/lib/rabbitmq                     # disk for persistence steps
rabbitmqctl force_reset                     # last resort: wipe + rejoin cluster

Conclusion

BOOT FAILED means an ordered startup step errored and the node aborted before running. The startup tuple names the culprit — config parse, Mnesia/schema, a listener bind, a plugin, or permissions/disk — so read it first. Fix config and port issues in place; for local schema corruption in a healthy cluster, reset the node and re-sync from peers rather than editing data files. Clean shutdowns, staged config changes, and cluster-wide upgrades before feature flags prevent most boot failures.