Upgrading RabbitMQ is one of those operations that should be straightforward but routinely catches teams off guard. The version path constraints are non-obvious, the Erlang dependency adds another moving part, and the cost of getting it wrong in production is high.
This post covers the two strategies that work — rolling upgrade and blue-green deployment — and the pre-upgrade steps that most teams miss, including feature flag enablement and Erlang version compatibility checks.
Why do RabbitMQ upgrades go wrong?
The most common failure pattern is a team that hasn't upgraded in a year or more, decides they want to jump to the latest version, and skips the intermediate steps the version upgrade path requires.
"A lot of times what companies struggle with, or they forget, is they don't do frequent upgrades. Sometimes it takes a couple years to do an upgrade. And if they try to go from where they are straight to the latest, they get a bunch of unforeseen issues — because what they should have done is upgrade step by step."
— Jeff Sogolov, AceMQ Engineer, Lucidya engagement session, May 2025
RabbitMQ has a defined upgrade path. You cannot skip major versions. If you're on 3.12, you must upgrade to 3.13 before you can upgrade to 4.x. Trying to jump directly causes cluster instability and compatibility issues that are difficult to diagnose.
What is the required upgrade path from 3.x to 4.x?
The version upgrade path is documented by Broadcom and must be followed precisely. The key rule: you can only upgrade one major version at a time.
From 3.12 → must go to 3.13 → then to 4.x. You cannot go from 3.12 directly to 4.1. If you're further behind — on 3.10 or 3.11 — you must step through each major version in sequence.
Each step before upgrading also requires enabling all feature flags on the current version before proceeding:
rabbitmqctl enable_feature_flag allSkipping feature flag enablement before a version jump is a common source of upgrade failures. Always confirm all flags show as enabled before moving to the next version.
What about Erlang compatibility?
Every RabbitMQ version specifies a minimum and maximum supported Erlang version. Upgrading RabbitMQ without upgrading Erlang to the required version first will cause the new RabbitMQ version to fail.
Key Erlang checkpoints for the 3.12 → 3.13 → 4.x path:
- 3.12 supports Erlang 25.x minimum
- 3.13 requires Erlang 26 minimum (26.2 recommended)
- 4.x also requires Erlang 26.2 minimum
"You can upgrade Erlang from 25 to 26.2 directly. Once you're on 26.2, you upgrade RabbitMQ to 3.13 — you already have the right Erlang. Then from 3.13 to 4.1, same Erlang version still applies."
— Jeff Sogolov, AceMQ Engineer, Lucidya session, May 2025
Strategy 1: Rolling Upgrade (In-Place)
A rolling upgrade upgrades your existing cluster nodes one at a time, without creating a new cluster. You stop one node, upgrade RabbitMQ (and Erlang if needed), restart it, then move to the next node.
How it works:
- Stop node 1 (service only — not the OS)
- Upgrade Erlang on node 1 to the required version
- Upgrade RabbitMQ on node 1 to the target version
- Start the RabbitMQ service on node 1
- Confirm node 1 has rejoined the cluster and is healthy
- Repeat for nodes 2 and 3
During the rolling upgrade, your cluster runs mixed versions temporarily. This is supported within a single major version but not across major version boundaries. Do rolling upgrades during low-traffic periods — upgrading under heavy load adds risk as quorum replication and message syncing create additional overhead.
Pros: No new infrastructure required, simpler orchestration, uses existing cluster membership. Cons: Brief per-node restarts cause connection disruption; must be done during low traffic.
Strategy 2: Blue-Green Deployment
A blue-green deployment creates a brand-new cluster (green) alongside your existing cluster (blue), migrates traffic to the new cluster using federation, and decommissions the old one once the transition is complete.
How it works:
- Provision a new cluster (green) on the target RabbitMQ and Erlang version
- Configure a federated queue upstream on the green cluster pointing to the blue cluster
- As consumers are moved to the green cluster, federation pulls messages from blue to green automatically
- Once all consumers are on green, move producers to green
- Once producers are moved, drain any remaining messages from blue using the shovel plugin
- Decommission the blue cluster
Key distinction: Use federated queues, not federated exchanges. With federated queues, when a consumer is present on the downstream (green) cluster, messages are pulled from the upstream (blue) cluster and consumed there — they don't persist on both sides.
"Blue-green is zero downtime. You can do it at any time — there's no maintenance mode. The cost is that you have two clusters running at the same time, which some companies can't afford, especially on-prem. But for AWS-based deployments where you can spin up new clusters easily, it makes a lot of sense."
— Jeff Sogolov, AceMQ Engineer, Lucidya session, May 2025
Pros: Zero-downtime migration, can be done at any time. Cons: Requires temporary double infrastructure, more configuration steps.
Pre-upgrade checklist
Before starting any RabbitMQ upgrade:
- Confirm current RabbitMQ version and identify the required upgrade path
- Check the Erlang compatibility matrix for target and intermediate versions
- Enable all feature flags on the current version (rabbitmqctl enable_feature_flag all)
- Back up cluster definitions (topology, users, permissions) via Management API
- Validate staging environment upgrade end-to-end before touching production
- Confirm load balancer health check behavior with nodes taken offline
- Test client reconnect behavior in staging under simulated node restarts
- Schedule during lowest-traffic window if using rolling upgrade
- Have rollback plan documented before starting
Multi-version RabbitMQ upgrades — especially the 3.x to 4.x jump — are one of the most common engagement types we handle. If you'd like help scoping the upgrade, designing the migration approach, or having an AceMQ engineer run it during your maintenance window, contact our team.