🚨 RabbitMQ Error Guide: 'operation queue.declare caused a channel exception' Declare Failures

Exact Error Message

Several distinct precondition failures surface as operation queue.declare caused a channel exception (or queue.delete). Unlike a plain inequivalent-arg mismatch, these come from invalid arguments, passive declares against missing queues, unsupported argument combinations, or conditional deletes that cannot proceed:

Channel error on connection <0.5210.0> (10.0.6.71:52004 -> 10.0.4.21:5672, vhost: '/', user: 'app'):
operation queue.declare caused a channel exception precondition_failed:
invalid arg 'x-queue-type' for queue 'events' in vhost '/': {unsupported_queue_type,<<"stream">>}

operation queue.declare caused a channel exception not_found:
no queue 'reports' in vhost '/'

operation queue.delete caused a channel exception precondition_failed:
queue 'tasks' in vhost '/' in use

What the Error Means

queue.declare is an assertion that either creates a queue or validates an existing one. When the arguments themselves are invalid (wrong type, unsupported value, illegal combination), or when you ask the broker to assert something it cannot satisfy (a passive declare on a queue that does not exist), the broker closes the channel with a precondition or not-found exception. The companion queue.delete raises a precondition failure when its conditions — if-unused or if-empty — are not met.

This family is distinct from inequivalent arg: there the queue exists and your flags merely disagree with it. Here the declaration or delete is structurally impossible to honor, or the arguments are malformed.

Common Causes

1. Unsupported or misspelled x-queue-type

Asking for x-queue-type=stream on a broker/plugin that does not support streams, or a typo like quorom, yields invalid arg 'x-queue-type' / unsupported_queue_type.

2. Argument value of the wrong type

Passing x-message-ttl as a string "60000" instead of an integer, or a negative TTL/max-length, is rejected as an invalid argument rather than an inequivalent one.

3. Passive declare on a non-existent queue

A queue.declare with passive=true only checks for existence and never creates. If the queue is missing, the broker returns NOT_FOUND - no queue '...' and closes the channel.

4. Illegal argument combinations for a queue type

Quorum queues reject classic-only arguments (e.g. x-max-priority, x-queue-mode, certain TTL/overflow combos). Declaring a quorum queue with priority support produces a precondition failure.

5. queue.delete if-unused with active consumers

queue.delete with if-unused=true fails with queue ... in use when consumers are still attached. Similarly if-empty=true fails if the queue holds messages.

6. Exclusive/auto-delete or name-policy violations

Declaring a queue with a reserved name prefix (amq.) or contradictory flags can also be rejected at declare time.

How to Reproduce the Error

Trigger a passive declare on a queue that does not exist, and a conditional delete on a queue with messages:

# Passive declare of a non-existent queue -> NOT_FOUND
rabbitmqadmin declare queue name=does-not-exist passive=true

*** Error: 404 NOT_FOUND - no queue 'does-not-exist' in vhost '/'

# Create a queue, add a message, then delete if-empty -> PRECONDITION_FAILED
rabbitmqadmin declare queue name=qd-demo durable=true
rabbitmqadmin publish routing_key=qd-demo payload="x"
rabbitmqadmin delete queue name=qd-demo if_empty=true

*** Error: 406 PRECONDITION_FAILED - queue 'qd-demo' in vhost '/' not empty

Diagnostic Commands

# Live queue type, flags, and arguments to compare against your declaration
rabbitmqctl list_queues name type durable auto_delete exclusive arguments consumers messages

# Which broker features/queue types and plugins are enabled
rabbitmq-diagnostics list_feature_flags
rabbitmqctl list_queue_types

# Consumers attached (relevant for delete if-unused)
rabbitmqctl list_consumers queue_name consumer_tag channel_pid

# The declare/delete exception and offending arg in the log
journalctl -u rabbitmq-server --since "15 min ago" | grep -iE "queue.declare|queue.delete|invalid arg|not_found|in use|not empty"

# Confirm the broker is healthy before deeper debugging
rabbitmq-diagnostics check_running

list_queue_types confirms whether quorum, classic, or stream are actually available, settling unsupported-type questions immediately.

Step-by-Step Resolution

Step 1: Read which clause failed

Distinguish invalid arg (malformed argument), not_found (passive declare / missing queue), and in use / not empty (conditional delete). The message names the exact problem.

Step 2: Fix malformed arguments

rabbitmqctl list_queue_types

Ensure x-queue-type is one your broker supports, spelled correctly. Pass numeric arguments (x-message-ttl, x-max-length) as integers, never strings, and use non-negative values. Remove arguments unsupported by the chosen queue type (e.g. x-max-priority on quorum queues).

Step 3: Stop passive-declaring queues that may not exist

If you use passive=true to check existence, handle the NOT_FOUND gracefully (create the queue first via your provisioning step). Reserve passive declares for queues you are certain exist.

Step 4: Resolve conditional-delete failures

rabbitmqctl list_queues name consumers messages | grep <QUEUE>
rabbitmqctl list_consumers queue_name | grep <QUEUE>

For if-unused, stop the consumers first (or drop the condition). For if-empty, drain or consume the remaining messages, then retry the delete.

Step 5: Recreate when a type/argument is immutable

Queue type and most structural arguments cannot change in place. If your desired definition differs, drain the queue and recreate it with the correct, supported arguments.

Step 6: Verify

rabbitmqctl list_queues name type arguments | grep <QUEUE>

The queue should now reflect the intended type and arguments, and the declare/delete should succeed.

Prevention and Best Practices

• Validate queue arguments (types, ranges, supported queue types) in a shared client config or schema before declaring.
• Provision queues once from a canonical definitions file and have apps declare passively where possible.
• Check rabbitmqctl list_queue_types and feature flags before adopting streams or quorum queues across the fleet.
• Use if-unused/if-empty deletes deliberately, with a drain/stop-consumers step, or accept the precondition failure as expected.
• Never pass numeric arguments as strings; many client bugs come from JSON or env-var coercion.
• Keep a CI check that lints declared queue arguments against the canonical definitions.

Related Errors

• PRECONDITION_FAILED - inequivalent arg — the queue exists and your flags merely disagree; covered in a separate guide.
• NOT_FOUND - no queue/exchange — a passive declare or bind against something that does not exist.
• RESOURCE_LOCKED — an exclusive queue owned by another connection blocks your declare.
• CHANNEL_ERROR — reusing the channel that this declare/delete exception closed.
• ACCESS_REFUSED — the user lacks configure/write permissions to declare or delete in the vhost.

Frequently Asked Questions

How is this different from inequivalent arg? Inequivalent arg means an existing queue’s properties differ from yours. These failures mean the arguments are invalid, the queue is missing for a passive declare, or a delete condition is unmet.

Why does a passive declare fail instead of creating the queue? passive=true is a check-only mode by design — it never creates. Use a normal declare (or provision first) if you want creation.

Can I change a queue’s type by redeclaring it? No. Type is fixed at creation. You must delete and recreate the queue to change it.

Why can’t I delete a queue with if-unused? Consumers are still attached. Stop them first, or remove the if-unused condition to force the delete.

Are quorum queues stricter about arguments? Yes. They reject several classic-only arguments such as priority and certain modes, surfacing as invalid-arg precondition failures. See the RabbitMQ guides for type-specific notes.