Troubleshooting RabbitMQ: Diagnosing Queue and Message Problems with Commands

When a RabbitMQ queue looks stuck, the worst first move is usually to purge it. The second-worst move is to restart the broker and hope the problem clears. Most queue problems leave a trail: ready messages, unacked messages, missing consumers, blocked publishers, unroutable messages, a dead-letter queue filling quietly, or a consumer that is connected but not acknowledging anything.

This guide uses RabbitMQ commands to narrow that down from the terminal. I lean on rabbitmqctl for broker-side state and rabbitmqadmin when you need management API operations such as safely sampling a message. The examples assume the default virtual host unless a -p <vhost> option is shown. In real systems, always include the vhost; many false diagnoses happen because someone checks / while the application uses payments or prod.

Understanding rabbitmqctl

The rabbitmqctl command acts as the command-line interface (CLI) for interacting with the RabbitMQ management layer. It allows you to manage users, permissions, exchanges, queues, bindings, and most importantly for troubleshooting, examine the runtime statistics of the broker.

Note on Execution: Most commands require root privileges or the user running the command to be a member of the rabbitmq group, or you may need to use sudo.

Diagnosing Queue Backlogs and Stuck Messages

One of the most common issues is a growing queue, indicating that messages are being produced faster than they are being consumed, or consumers have stopped processing.

Start with the queue, but ask for the right columns

The default list_queues output is too thin for troubleshooting. Ask for the columns that separate "waiting to be delivered" from "delivered but not acknowledged."

rabbitmqctl -p / list_queues name messages_ready messages_unacknowledged messages consumers state

Read it like this:

Symptom	Likely meaning
messages_ready growing, consumers is 0	No active consumer is subscribed to the queue. Check deployments, credentials, vhost, and queue name.
messages_ready growing, consumers present	Consumers are too slow, blocked, or prefetch is too low for the workload.
messages_unacknowledged high and stable	Consumers received messages but are not acking them. Look for stuck handlers or a prefetch value that is too high.
state is not running	The queue may be unavailable, synchronizing, or affected by a node issue. Check cluster and queue leader state.

For quorum queues, add leader and membership columns:

rabbitmqctl -p / list_queues name type leader members online messages_ready messages_unacknowledged consumers state

That matters because a queue can have healthy consumers on one node while the leader is somewhere else, or a quorum queue can be waiting for enough members to come online.

If the list is long, filter with standard shell tools:

rabbitmqctl -p / list_queues name messages_ready messages_unacknowledged consumers state \
  | awk '$2 > 0 || $3 > 0 || $4 == 0'

Check whether the broker is blocking publishers

rabbitmqctl status
rabbitmq-diagnostics alarms

Memory and disk alarms do not mean the queue is misconfigured, but they explain a lot of "nothing is moving" incidents. When RabbitMQ raises a memory or disk free alarm, it can block publishing connections. Consumers may still drain messages, so the visible symptom may be uneven: some queues shrink, others stop receiving new work, and publishers time out.

Also check listeners and node health:

rabbitmq-diagnostics ping
rabbitmq-diagnostics listeners
rabbitmq-diagnostics check_running
rabbitmq-diagnostics check_local_alarms

Inspect consumers without guessing

list_connections tells you who is connected. list_channels tells you whether those connections opened channels and how much work they are holding.

rabbitmqctl list_connections name user peer_host peer_port state channels recv_oct send_oct
rabbitmqctl list_channels connection name number consumer_count messages_unacknowledged prefetch_count state

The useful patterns are simple:

• No connection from the expected host: the application is down, cannot resolve the broker, cannot authenticate, or is connecting to another environment.
• Connection exists, but no channels: the client connected and then failed before declaring or consuming.
• Channels exist, but consumer_count is 0: the app may be publishing only, or the consumer subscription failed.
• messages_unacknowledged is high on one channel: that consumer has work in memory and is not returning acks quickly.

If you use named connections, include connection_name in your client configuration. A line like 10.42.8.17:52344 -> 10.42.1.20:5672 is less helpful than billing-worker-7.

Verify bindings before blaming consumers

When a queue is empty but the application says it published messages, routing is the next place to look.

rabbitmqctl -p / list_exchanges name type durable auto_delete internal arguments
rabbitmqctl -p / list_bindings source_name source_kind destination_name destination_kind routing_key arguments

A direct exchange requires an exact routing-key match. A topic exchange uses * for one word and # for zero or more words. A fanout exchange ignores routing keys. If the exchange has no matching binding and no alternate exchange, the message is unroutable. It is not secretly waiting somewhere.

For publisher-side confirmation, use mandatory publishing and handle returned messages in the client. On the broker side, the management UI and metrics are usually better than rabbitmqctl for rates, but list_bindings is enough to catch the common mistakes: wrong vhost, wrong exchange, misspelled routing key, or a queue bound to the old exchange after a deployment.

Sample a message safely

There is no general rabbitmqctl queue_get command in modern RabbitMQ. Use the management plugin through rabbitmqadmin or the HTTP API. Do this carefully: depending on the ack mode, getting messages can remove or requeue them.

rabbitmqadmin -V / get queue=orders.pending count=3 ackmode=ack_requeue_true

Use this to answer narrow questions: is the payload valid JSON, is the message type what the consumer expects, is a required header missing, is the routing key what the producer team said it was? Do not use it as a bulk inspection tool on a busy production queue.

Look for dead-letter movement

Delayed processing often shows up as a dead-letter queue quietly growing.

rabbitmqctl -p / list_queues name messages_ready messages_unacknowledged arguments policy
rabbitmqctl -p / list_bindings source_name destination_name routing_key arguments \
  | grep -E 'dead|dlx|retry|parking'

Queue arguments such as x-dead-letter-exchange, x-dead-letter-routing-key, x-message-ttl, x-max-length, and x-overflow change where messages go when they expire, are rejected, or hit length limits. If the application retries by dead-lettering through delay queues, a bad binding can create a loop. The symptom looks like "delayed messages," but the real issue is that messages are cycling between queues instead of reaching a final processing queue or a parking lot queue.

A practical command sequence

When someone reports "orders are stuck," I usually run this sequence:

rabbitmq-diagnostics ping
rabbitmq-diagnostics check_local_alarms
rabbitmqctl -p orders list_queues name type messages_ready messages_unacknowledged consumers state
rabbitmqctl list_connections name user peer_host state channels
rabbitmqctl list_channels connection consumer_count messages_unacknowledged prefetch_count state
rabbitmqctl -p orders list_bindings source_name destination_name routing_key arguments

If messages_ready is high and consumers is zero, go to the consumer deployment. If messages_unacknowledged is high, go to the consumer logs and prefetch settings. If the queue is empty but publishers report success, inspect bindings and publisher confirms. If alarms are active, fix broker resource pressure before chasing application logic. This keeps the investigation grounded in what the broker is actually doing.