🐰 RabbitMQ Error: 'classic_queue_mirroring is deprecated' HA Policy Rejected

Exact Error Message

On RabbitMQ 3.13 the broker logs a deprecation warning when an ha-mode policy is in use:

[warning] <0.812.0> Deprecated features used:
[warning] <0.812.0>   * classic_queue_mirroring (deprecation phase: permitted_by_default)
[warning] <0.812.0> Consult https://www.rabbitmq.com/docs/deprecated-features for more details.

After upgrading to RabbitMQ 4.x, classic mirroring is removed, and applying the same policy produces:

Error:
Validation failed

Validation of policy "ha-all" failed:
key "ha-mode" is not recognised. Classic queue mirroring was removed in RabbitMQ 4.0.
Use quorum queues for replicated messaging.

What It Means

Classic mirrored queues (configured with ha-mode, ha-params, and ha-sync-mode policy keys) were RabbitMQ’s original approach to replicating a queue across nodes. They were deprecated in 3.x and removed in RabbitMQ 4.0. The deprecation-features framework flags any policy still using classic_queue_mirroring so you can migrate before the upgrade.

If you upgrade with mirroring policies still in place, those policies no longer replicate anything. Your queues become non-replicated classic queues, and the ha-* keys are rejected on the next set_policy call.

Common Causes

• A long-standing ha-mode: all or ha-mode: exactly policy carried forward from RabbitMQ 3.7/3.8.
• Infrastructure-as-code (definitions.json, Terraform, or Ansible) that still declares ha-mode policy keys.
• Clients or operators that assume mirrored queues still exist after a 4.x upgrade.
• A blue/green upgrade where the new cluster imports an old definitions file containing HA policies.

Diagnostic Commands

List whether the deprecated feature is actually in use:

rabbitmq-diagnostics list_deprecated_features --used

Show every policy and look for ha-mode, ha-params, or ha-sync-mode:

rabbitmqctl list_policies

Identify which queues are still classic (mirrored) rather than quorum:

rabbitmqctl list_queues name type durable messages --formatter=pretty_table

Check per-queue effective policy and mirroring state on 3.13 before you upgrade:

rabbitmq-diagnostics list_queues name policy state

Step-by-Step Resolution

1. Confirm the feature is in use and find the offending policies:

rabbitmq-diagnostics list_deprecated_features --used
rabbitmqctl list_policies

2. Remove the HA policy so it stops replicating and stops the warning:

rabbitmqctl clear_policy -p / ha-all

3. Create the replacement queues as quorum queues. Quorum queues cannot be converted in place, so declare a new queue with the quorum type:

rabbitmqctl set_policy -p / quorum-defaults "^orders\." \
  '{"max-length": 100000}' --apply-to quorum_queues

Then declare the new queue from your client with the x-queue-type argument:

channel.queue_declare(queue='orders.new', durable=True,
                      arguments={'x-queue-type': 'quorum'})

4. Drain the old mirrored queue into the quorum queue. Point a shovel or your consumers at the old queue, republish to the new one, and cut publishers over once the old queue is empty.

5. Verify the new queues are quorum and replicated across nodes:

rabbitmqctl list_queues name type members

6. Re-run the deprecation check to confirm nothing still uses classic mirroring before the 4.x upgrade:

rabbitmq-diagnostics list_deprecated_features --used

An empty result means you are clear to upgrade.

Prevention

• Audit definitions.json and any IaC for ha-mode/ha-params/ha-sync-mode keys and delete them before upgrading.
• Standardise on quorum queues for all new replicated workloads; treat classic queues as non-replicated only.
• Run rabbitmq-diagnostics list_deprecated_features --used as a pre-upgrade gate in CI.
• Set x-queue-type: quorum explicitly at declaration time so queue type is never left to defaults.
• Watch broker logs for Deprecated features used warnings and treat them as upgrade blockers, not noise.

Related Errors

• key "ha-sync-mode" is not recognised — another removed classic-mirroring policy key.
• queue type 'quorum' requires all nodes to be running — a quorum-queue availability issue, not mirroring.
• operation queue.declare caused a channel exception precondition_failed — redeclaring an existing queue with a different x-queue-type.
• Deprecated features used: transient_nonexcl_queues — a different deprecated feature flagged by the same framework.

Frequently Asked Questions

Can I convert a mirrored queue to a quorum queue in place? No. Queue type is fixed at declaration. You must declare a new quorum queue and migrate messages into it with a shovel or your consumers. For a migration checklist you can adapt, see the RabbitMQ prompt library.

Do I have to remove the policy before upgrading to 4.x? Yes. Leaving ha-mode keys in place means the policy is rejected after the upgrade and your queues silently stop being replicated.

Will quorum queues behave exactly like ha-mode: all? They replicate to a majority of nodes and survive node loss, but they use Raft consensus and require an odd number of members. Sizing and failure semantics differ, so test throughput first.

How do I find every queue still using mirroring? Run rabbitmq-diagnostics list_deprecated_features --used and rabbitmqctl list_policies, then cross-reference with list_queues name type. For more messaging fixes, see the RabbitMQ guides.