Upgrading Amazon MQ for RabbitMQ 3.13 to 4.2 In-Place: A Practical Walkthrough

Amazon MQ now supports in-place major version upgrades from RabbitMQ 3.13 to 4.2. Before this, moving from 3.x to 4.x meant standing up a new broker and migrating your data and clients over. An in-place upgrade happens on the same broker resource and, per AWS, preserves your broker configuration, queues, exchanges, bindings, users, and policies — so there's no separate data migration step. That does not mean zero application impact: RabbitMQ 4 introduces breaking changes (client library minimums, removed Global QoS, a new default queue type, lower resource limits, and more — covered below) that may require code or configuration updates. Test your clients against 4.2 before you cut over.

RabbitMQ 4 is a meaningful jump: classic mirrored queues lose replication, quorum queues become the recommended replicated type, and Khepri becomes the default metadata store in 4.2. Those changes are exactly why the upgrade has guardrails you need to clear first.

What You Should Know Before Starting

Three things about an in-place upgrade shape the whole plan:

• It causes downtime. Amazon MQ blocks all connections during the upgrade to perform it safely. Upgrade duration scales with queue count and queue depth — the more queues and messages you have, the longer the outage. Drain queues as short as you can beforehand.
• RabbitMQ 4.2 requires the mq.m7g instance type. If you are on an older instance family, that is a separate step with its own reboot.
• Amazon MQ runs an eligibility check at the start of the upgrade. If you still have classic queues, or if the Khepri metadata store feature flag is enabled on the 3.13 broker, it refuses the upgrade and parks the broker in CRITICAL_ACTION_REQUIRED with code RABBITMQ_BROKER_NOT_UPGRADEABLE_TO_V4. Better to catch this yourself first.
• If Khepri is already enabled on your 3.13 broker, there is no in-place upgrade path at all. This is a hard blocker, not something you clear during the eligibility check — you must use a blue/green deployment (stand up a new 4.2 broker and migrate) instead. Confirm the Khepri feature flag state before you plan an in-place upgrade.

Prerequisites

• An Amazon MQ for RabbitMQ 3.13 broker (upgrade path is specifically 3.13 → 4.2)
• Permissions for UpdateBroker, RebootBroker, and DescribeBroker
• If your broker uses a customer managed KMS key: the calling IAM role needs kms:CreateGrant and kms:DescribeKey on that key (see the KMS note below)
• A maintenance window — this is not a zero-downtime operation

The Upgrade in Three Steps

Step 1: Instance type ──▶ mq.m7g  (reboot)
Step 2: Migrate classic/mirrored queues ──▶ quorum queues
Step 3: Set pending engine version 4.2 ──▶ reboot ──▶ upgrade runs (downtime)

Step 1: Move to mq.m7g

RabbitMQ 4.2 runs only on the mq.m7g instance family. If your broker is already on mq.m7g, skip to Step 2.

# Change the instance type
aws mq update-broker \
  --broker-id b-1234abcd-... \
  --host-instance-type mq.m7g.large

# Apply it (or wait for the next maintenance window)
aws mq reboot-broker --broker-id b-1234abcd-...

This reboot is a separate outage from the version upgrade. If you can, batch it into the same maintenance window as Step 3 so you take one planned outage instead of two.

Step 2: Migrate classic queues to quorum queues

This is the step teams underestimate. In RabbitMQ 4, classic queues still exist but lose their mirroring/replication — they become a non-replicated queue type. Amazon MQ will not perform the upgrade while the broker still has classic queues, so you must convert them to quorum queues (the replicated type) first.

Amazon MQ provides a queue migration tool for this. Access it two ways:

• RabbitMQ web console: Admin > Queue Migration
• HTTP API: the same tool, scriptable

Before you migrate, understand what changes when a queue becomes a quorum queue, because the semantics are not identical:

Behavior	Classic (mirrored)	Quorum
Replication	Mirrored to followers	Raft consensus across nodes
Redelivery handling	No redelivery limit applied	Default redelivery limit of 20 — messages redelivered 20+ times are dead-lettered or dropped
Priorities	1–255 fine-grained	Two levels: normal (0–4, and unset) and high (>4), delivered at a 2:1 fair-share ratio
Best for	Legacy workloads	Durable, replicated FIFO — the RabbitMQ 4 default

Action items for this step:

• Inventory every queue and its type (rabbitmqctl list_queues name type or the management API).
• Remove any classic mirroring policies before/after conversion so they don't linger.
• If you rely on fine-grained message priorities, note that quorum queues collapse them to just high (>4) and normal (0–4), delivered at a 2:1 ratio rather than strict priority — test that your consumers still behave correctly.
• If your consumers depend on unlimited redelivery, be aware quorum queues apply a default redelivery limit of 20 and will dead-letter or drop messages beyond that. AWS is explicit here: if 20 deliveries per message is a common scenario for a queue, you must configure a dead-lettering target or a higher limit — the recommended way is via a policy — to avoid data loss.
• The default queue type flips to quorum on RabbitMQ 4.2. If any of your code or tooling declares a queue without specifying a type, you'll now get a quorum queue instead of a classic one. Make queue-type declarations explicit before you upgrade.

Step 3: Upgrade the engine version

With the instance type on mq.m7g and no classic queues remaining, set the pending engine version and reboot.

# Set the target engine version
aws mq update-broker \
  --broker-id b-1234abcd-... \
  --engine-version 4.2

# Apply the upgrade (this is when the downtime happens)
aws mq reboot-broker --broker-id b-1234abcd-...

At the start of the upgrade, Amazon MQ runs its eligibility check. If it finds classic queues or the Khepri feature flag enabled, it stops, keeps the broker available for publish/consume on 3.13, and raises RABBITMQ_BROKER_NOT_UPGRADEABLE_TO_V4. If that happens, resolve the flagged issue and retry — you don't lose the broker.

Escape hatch: you can clear the CRITICAL_ACTION_REQUIRED state at any point by using UpdateBroker to set the engine version back to 3.13. Useful if you triggered the upgrade before finishing the prep work.

KMS note (customer managed keys only)

If your 3.13 broker is encrypted with a customer managed key, the IAM role calling UpdateBroker for the 4.2 upgrade must have kms:CreateGrant and kms:DescribeKey on the broker's key. Without them, UpdateBroker returns a 403 asking for grant permissions. Add the two permissions for the key ARN and retry.

Monitoring the Upgrade

Watch progress with DescribeBroker or the broker's state in the Amazon MQ console:

aws mq describe-broker --broker-id b-1234abcd-... \
  --query '{state: BrokerState, engine: EngineVersion, pending: PendingEngineVersion}'

• BrokerState moves through reboot/upgrade states and back to RUNNING when done.
• A CRITICAL_ACTION_REQUIRED state with RABBITMQ_BROKER_NOT_UPGRADEABLE_TO_V4 means the eligibility check failed — see the troubleshooting doc.

The Gotcha After the Upgrade: Lower Default Resource Limits

This is the one that surprises people after a "successful" upgrade. RabbitMQ 4 introduces default resource limits for connections, channels, consumers per channel, queues, vhosts, shovels, exchanges, and maximum message size. On RabbitMQ 3, these were effectively set to the maximums. After the in-place upgrade, Amazon MQ applies the RabbitMQ 4 defaults, which are lower.

If your workload was running above those new defaults, the broker can start rejecting new connections, channels, or queue declarations once it's on 4.2 — even though the upgrade itself succeeded.

Before you upgrade: check your current peak usage against the RabbitMQ 4 default resource limits for your instance type and deployment mode. After you upgrade: update the broker configuration to raise the limits back to what your workload needs.

Other Breaking Changes to Check

A few more RabbitMQ 4 changes can affect you depending on your stack:

• Client library compatibility. The Node.js amqplib client older than 0.10.7 — or any AMQP client configured with frame_max < 8192 — will not be able to connect to RabbitMQ 4. Bump your client versions before the cutover.
• Global QoS removed. If your consumers set a single shared prefetch for an entire channel (global QoS), switch to per-consumer (non-global) QoS.
• Per-queue CloudWatch metrics are gone on RabbitMQ 4. Amazon MQ still vends broker-level metrics to CloudWatch, but not per-queue metrics — query those through the RabbitMQ management API instead (at one-minute-or-longer intervals). If you have alarms on per-queue CloudWatch metrics today, they'll go blank after the upgrade.
• Transient, non-exclusive queues are no longer supported; use queue TTL to auto-delete idle queues.
• Local Random exchanges and message interceptors are not supported on Amazon MQ for RabbitMQ 4. If your application relies on either, you'll need to rework that logic before upgrading.

Pre-Upgrade Checklist

• [ ] Broker is on RabbitMQ 3.13
• [ ] Khepri feature flag is NOT enabled — if it is, in-place is not possible; plan a blue/green migration instead
• [ ] Instance type is (or will be moved to) mq.m7g
• [ ] No classic or classic mirrored queues remain — migrate to quorum queues
• [ ] Classic mirroring policies removed
• [ ] Queue-type declarations made explicit (default flips to quorum on 4.2)
• [ ] Consumers validated against quorum queue priority (high/normal, 2:1) and the redelivery limit of 20; dead-letter target in place
• [ ] Peak connection/channel/queue counts compared against RabbitMQ 4 defaults; plan to raise limits post-upgrade
• [ ] Client libraries checked — amqplib >= 0.10.7 and frame_max >= 8192
• [ ] Global QoS replaced with per-consumer QoS; per-queue CloudWatch alarms re-pointed to the management API
• [ ] IAM role has kms:CreateGrant + kms:DescribeKey if using a customer managed key
• [ ] Maintenance window scheduled; queues drained as short as possible to minimize downtime

Conclusion

An in-place 3.13 → 4.2 upgrade happens on the same broker resource with no separate data migration, which makes it attractive. The catch is that RabbitMQ 4 removed classic queue mirroring, tightened default resource limits, and introduced client-side breaking changes — so the real work is the preparation: confirm Khepri isn't enabled (or you're on the blue/green path instead), get onto mq.m7g, convert classic queues to quorum queues, validate your clients against 4.2, and plan to restore your resource limits afterward. Do that prep, schedule a maintenance window sized to your queue depth, and the actual upgrade is a set-version-and-reboot operation.

Additional Resources

• In-place upgrade from RabbitMQ 3 to 4 (Developer Guide)
• Amazon MQ now supports in-place major version upgrades for RabbitMQ 4
• Migrating from classic queues to quorum queues on Amazon MQ for RabbitMQ
• RabbitMQ 4 on Amazon MQ (defaults, quorum queue priorities, Khepri)
• Troubleshooting: RABBITMQ_BROKER_NOT_UPGRADEABLE_TO_V4
• Implementing message prioritization with quorum queues (AWS Compute Blog)