Upgrading RabbitMQ 3.x to 4.x Without Downtime: Rolling vs. Blue-Green

Most 3.x to 4.x upgrades that go wrong fail on one of a short list of changes. None of them are surprises if you read the 4.0 release notes, but each one is easy to miss in a large estate that grew up on 3.8 and 3.9 conventions.

Classic queue mirroring is gone. Mirrored classic queues (the ha-mode and ha-params policy keys) were deprecated in 3.9 and removed in 4.0. A 4.x node does not mirror classic queues, so any queue that relied on an HA policy for replication becomes a single-node queue the moment the policy stops applying. This is the one change that must be handled before the upgrade rather than after: migrate each mirrored queue to a quorum queue, then delete the HA policies. rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policy tells you whether any remain. We cover the tradeoffs in our classic vs quorum queues post.

Transient non-exclusive queues are deprecated. Non-durable queues that are not exclusive to a connection are flagged as a deprecated feature and can be denied by configuration. They still work in 4.x, but plan on declaring durable queues everywhere and using exclusive queues for genuinely per-connection state.

The default queue type. Declaring a queue without x-queue-type still gives you a classic queue unless the virtual host sets default_queue_type. Set it to quorum per vhost for new workloads, and make sure client code that declares queues passes an explicit x-queue-type so nobody is surprised by a vhost-level default.

AMQP 1.0 is a core protocol. In 4.0 the separate AMQP 1.0 plugin is no longer needed; 1.0 is implemented natively alongside 0-9-1 on the same listener. Existing 0-9-1 clients are unaffected. Teams that were running the old plugin should remove it from their enabled plugins list, and teams that want 1.0 should move to the maintained 1.0 client libraries rather than legacy ones.

Khepri as the metadata store. Khepri, the Raft-based replacement for Mnesia, shipped as experimental in 3.13 and is supported in 4.x, but it is opt-in. Nodes keep using Mnesia after the upgrade until you deliberately enable the khepri_db feature flag. Treat that as a separate change with its own test window, not a side effect of the version bump.

Feature flags must all be enabled first. A 3.13 cluster with any stable feature flag still disabled cannot join a 4.x node, and the 4.x node refuses to start against it. Enable everything before the first node moves.

Plugins and the management UI. Plugins compiled for 3.x need 4.x builds. The management plugin itself carries forward, but it drops the mirroring views and the AMQP 1.0 plugin becomes a no-op. Audit any community plugin before assuming it works.

MQTT 5. MQTT 5 support arrived in 3.13 and carries into 4.x. If you are coming from 3.12 or older, your MQTT clients gain it as part of the path.

Erlang. 4.x requires Erlang/OTP 26 or later. If your nodes are still on OTP 25, the Erlang upgrade happens as part of the rolling upgrade, one node at a time. See our note on Erlang 26 end of life and RabbitMQ before you pick a target.

3.13 is the last 3.x series. The community support window for it is short, and once it closes there are no upstream security patches for any 3.x version. That is the honest constraint that drives the decision.

Staying on 3.13 is reasonable in exactly one case: you have a commercial or extended support arrangement that backports security fixes to the version you are running. Without that, a 3.13 cluster is a CVE clock. Our extended LTS support covers 3.8.x through 3.13.x with backported patches, which is what lets clients run older series on a schedule they control rather than one dictated by the upstream calendar. It buys time; it does not remove the need to plan the move.

Upgrade when all four of these are true:

1. Mirrored classic queues are gone and no HA policies remain.
2. Every stable feature flag is enabled on every node.
3. Erlang is on OTP 26 or later, or you are ready to move it during the rolling upgrade.
4. Client applications are on maintained library versions that behave correctly against quorum queues (correct handling of x-delivery-limit, dead lettering, and reconnect).

Upgrade sooner than your maintenance calendar suggests if you need AMQP 1.0 without the plugin, MQTT 5 on an older 3.x, or the 4.x quorum queue improvements, which include message priorities and a default delivery limit that stops poison messages from cycling forever.

If you are on 3.8 through 3.12, the answer is the same but the path is longer: get to 3.13 first, stabilise, then move to 4.x. We run both halves for clients and the upgrade service is scoped that way.

This is the sequence we follow on client clusters. It assumes a three or five node cluster, quorum queues for anything that matters, and clients that reconnect on connection loss.

1. Inventory. Record versions, Erlang versions, enabled plugins, and every policy. Run rabbitmq-diagnostics check_if_any_deprecated_features_are_used and rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policy on any node. Both must come back clean before you continue.
2. Enable all stable feature flags. rabbitmqctl enable_feature_flag all on one node applies cluster-wide. Confirm with rabbitmqctl list_feature_flags; anything still disabled blocks the upgrade.
3. Convert mirrored classic queues to quorum queues, flow by flow. Quorum queues cannot be converted in place. For each flow, declare the quorum queue, repoint consumers, repoint producers, drain the old queue, delete it. Do this per application so a mistake affects one flow, not the estate.
4. Verify the Erlang target. Confirm the OTP 26 or later package is available on every node and that it is the version your 4.x build was tested against.
5. Export definitions and take a backup. rabbitmqctl export_definitions plus a filesystem backup of the data directory on every node. The definitions export is what you rebuild from if the rollback boundary is crossed.
6. Upgrade one node at a time. Before stopping a node, run rabbitmq-upgrade await_online_quorum_plus_one so no quorum queue loses its majority while this node is out. Then rabbitmq-upgrade drain puts the node in maintenance mode, closes client connections gracefully, and transfers quorum queue leadership away. Stop the service, upgrade Erlang if needed, upgrade RabbitMQ, start it, and confirm it rejoined.
7. Wait for quorum queue members to catch up. rabbitmq-queues quorum_status <queue> on the busiest queues, or rabbitmq-diagnostics check_if_node_is_quorum_critical on the next node you intend to stop. Do not start the next node until this passes.
8. Verify clients reconnected. Connection counts in the management UI should return to baseline on the upgraded node. If a client library does not reconnect, fix it now, before the next node.
9. Repeat for each remaining node. The cluster runs mixed 3.13 and 4.x during this window. Do not change policies, add queues, or enable anything new until the last node is done.
10. Enable the new 4.x feature flags. After the final node is upgraded, rabbitmqctl enable_feature_flag all again. This is the rollback boundary: once a 4.x-only feature flag is enabled there is no downgrade path. Everything before this step can be reversed by restoring a node to 3.13.

rabbitmqctl enable_feature_flag all
rabbitmq-upgrade await_online_quorum_plus_one
rabbitmq-upgrade drain

Blue-green is the alternative when the cluster is small enough to rebuild, the definitions export is trustworthy, and you can afford to move clients by DNS or load balancer. It gives you a clean 4.x cluster and an intact 3.13 cluster to fall back to. We prefer it for clusters that have accumulated years of undocumented policies.

Either way, support covers the upgrade window with a 15-minute P1 response, which matters most between step 6 and step 10.