RabbitMQ speaks several protocols. AMQP 0-9-1 is the classic one and the one every Spring AMQP and Java client example on this page uses. Since RabbitMQ 4.0, AMQP 1.0 is supported natively by the core broker (no plugin): the same port 5672 accepts both, and the client chooses with a protocol header. Streams have their own binary protocol (a plugin), and MQTT and STOMP are available through plugins. A message published with one protocol can be consumed with another, with a conversion step when needed.

This page targets RabbitMQ 4.x. Where a feature needs a specific minor version it is stated (for example 4.3 introduced strict priorities and delayed retry for quorum queues). The hands-on chapter runs the rabbitmq:4-management image, which was 4.4.0 when this page was written.

The broker never "remembers" a client. If the connection drops, every channel, consumer, unacknowledged delivery and non-durable declaration of that client is gone. Unacked messages go back to their queue and will be redelivered (with the redelivered flag set), possibly to a different consumer. Good clients re-open the connection, recreate the topology (declarations are idempotent) and resume consuming. Spring AMQP and the Java client do this automatically by default; chapter 09 shows where the knobs are.

Routes to the queues whose binding key equals the routing key. Use it for classification by a fixed label: log severity, job type, a tenant name.

Copies every message to all bound queues and ignores the routing key. Use it for broadcast: notify audit, email and search-indexing independently, each with its own queue and consumers.

Routing keys are dot-separated words (order.eu.created). Binding keys are patterns: * substitutes exactly one word, # substitutes zero or more words. This is the workhorse for event routing because consumers choose their slice with a pattern.

Ignores the routing key and matches on the message headers instead. Each binding carries a map of header values plus x-match: all (default) requires every listed header to match, any requires at least one. It is useful when routing depends on several attributes at once and encoding them into a dotted key would be awkward. In practice topic exchanges cover most needs and are easier to read and reason about.

Every vhost has a pre-declared direct exchange with the empty name. When a queue is declared it is bound to it automatically with the queue name as key, so publishing with exchange "" and routing key tasks lands in queue tasks.

• Classic queue mirroring was removed in 4.0 (deprecated since 2021). Classic queues are now a non-replicated type. If you used mirrored classic queues for high availability, migrate to quorum queues (or streams). The docs describe a blue-green strategy for moving from 3.13.
• **Quorum queues got a default delivery-limit of 20 in 4.0.** A message returned to the queue more than 20 times is dropped, or dead-lettered if a DLX is configured. In 3.13 there was no limit. Set x-delivery-limit=-1 (or the delivery-limit policy key) to restore unlimited redelivery, which the docs advise only for rare compatibility cases. Since 4.3 the limit counts failed deliveries (x-delivery-count) and plain returns via nack do not count.
• Native AMQP 1.0 support in the core broker since 4.0, alongside AMQP 0-9-1 on the same port.
• Classic queue version 1 storage was removed in 4.0; version 2 is the only implementation and existing queues are converted at node start.
• Khepri, a Raft-based metadata store, is fully supported from 4.0 and is the recommended replacement for Mnesia. In the 4.4.0 image used on this page the khepri_db feature flag was enabled.
• 4.3 added delayed retry with linear back-off for quorum queues and strict 0 to 31 message priorities. It also made non-durable, non-exclusive classic queues impossible to declare unless you set deprecated_features.permit.transient_nonexcl_queues = true.
• Global QoS (a prefetch limit shared by all consumers of a channel) is a deprecated feature. In the 4.4.0 image rabbitmqctl list_deprecated_features showed global_qos as denied_by_default. Use per-consumer prefetch.

A quorum queue has a leader and followers, together called members (3 by default; x-quorum-initial-group-size changes it, and an odd number is recommended). Publishing goes to the leader, which appends the message to its replicated log and sends it to followers. A message is committed when a majority of members (N/2 + 1) have written it, and only then is the publisher confirmed. If the leader dies, the followers elect a new leader from the members that have the committed data, with no data loss for confirmed messages.

Consequences you should know: writes need a majority, so a minority partition cannot accept publishes to that queue; quorum queues always persist to disk and never keep the whole queue in memory; they do not support non-durable or exclusive queues (use single active consumer instead of exclusivity); and consumer prefetch is capped at 2,000 even if you ask for unlimited.

A policy applies settings to every queue whose name matches the pattern and can be changed at any time without redeclaring. Arguments set in code (x-delivery-limit, x-dead-letter-exchange) are baked in at declaration and cannot be changed without deleting the queue, which is why the docs recommend policies for anything that may change.

A stream is an append-only, replicated log inside RabbitMQ. Consumers read non-destructively from an offset, timestamp or the beginning, so many consumers can read the same data and replay it, much like a Kafka partition (page 02). Retention is by x-max-age or x-max-length-bytes, evaluated per segment file (default segment 500,000,000 bytes). Streams can be used from AMQP 0-9-1 clients (acks required, per-consumer prefetch required, no global QoS) or, for best throughput, through the dedicated stream protocol and its clients. Super streams partition a stream for parallelism. Streams complement queues; they do not replace them.

For a classic queue you need both: a durable queue and persistent messages. A persistent message in a non-durable queue vanishes at restart because the queue itself is deleted; a transient message in a durable queue is discarded when the node boots. Quorum queues and streams remove the foot-gun by always doing both.

A publisher puts its channel in confirm mode once. The broker then answers every publish, asynchronously, with basic.ack or basic.nack, identified by a sequence number the client keeps. Confirms are the only reliable way to know the broker took responsibility for a message. (AMQP transactions also exist but confirms are the recommended mechanism.)

Two details matter. A confirm says the message is safe in the queue, not that anyone consumed it; consumer acknowledgments are a separate mechanism (chapter 06). And for persistent messages the broker batches fsync calls, so a confirm for a single message on an idle queue can take a moment: that is the price of durability, not a fault.

With mandatory=true, an unroutable message is returned to the publisher through basic.return (Spring: a ReturnsCallback) before the confirm. Alternatively an alternate exchange (alternate-exchange policy key or argument) receives everything the primary exchange could not route, which lets the broker catch it into a "parking" queue with no publisher involvement.

Without a limit the broker pushes the entire queue at a consumer as fast as the network allows. Prefetch (basic.qos) caps the number of unacknowledged deliveries a consumer may hold. When it is reached the broker stops sending until an ack frees a slot. It is the single most influential consumer setting for both throughput and fairness.

• RabbitMQ applies prefetch_count per consumer on a channel, which differs from the AMQP 0-9-1 text (shared across the channel). A global (channel-wide) limit exists but is a deprecated feature and slower; avoid it.
• Spring AMQP's prefetchCount defaults to 250 (since version 2.0) and is ignored when the ack mode is NONE. Set it explicitly per listener container based on handler duration.
• basic.qos has no effect on basic.get.
• Example sizing (illustrative arithmetic): if a handler takes 5 ms and the network round trip is 1 ms, a prefetch of 1 leaves the consumer idle for roughly 1 ms out of every 6 ms. A prefetch of a few messages hides the round trip entirely. For handlers that take seconds, the round trip is irrelevant and a small prefetch (1 to 5) keeps work balanced.

If a consumer holds a delivery without acking it, the broker eventually closes the channel. The default timeout is 30 minutes (consumer_timeout, configurable globally or per queue with a policy). As of RabbitMQ 4.3 the timeout is enforced for quorum queues only, because stuck deliveries bloat the Raft log. Symptom of hitting it: the consumer logs a channel error mentioning a delivery acknowledgement timeout, and the message is redelivered. Fix: speed up the handler, raise the timeout deliberately, or hand long work to a separate worker and ack when it is accepted.

A dead letter exchange (DLX) is an ordinary exchange to which a queue republishes messages that die. A message is dead-lettered in four cases:

If a whole queue expires (x-expires), its messages are not dead-lettered. Configure the DLX with a policy (dead-letter-exchange, optional dead-letter-routing-key); if no routing key is set the message keeps its original key(s). If the DLX does not exist when needed, messages are silently dropped, so create it first. Each dead-lettering **adds an x-death header** and the first and last events are summarised in x-first-death-* and x-last-death-* headers. The real output below came from the lab in chapter 10: a message rejected from queue orders.new and read from the dead letter queue.

• The x-death array is ordered most recent first and is compressed by the {queue, reason} pair: the count field says how many times it happened. That is exactly the counter a retry loop needs.
• By default, dead-lettered messages are republished without publisher confirms, so in a cluster a dead-letter hop can lose messages if the target is unavailable. Quorum queues offer dead-letter-strategy=at-least-once, which retains the message until the DLX target confirmed it. It needs overflow=reject-publish and a configured DLX, and costs more memory and CPU. The default is at-most-once.
• RabbitMQ detects a dead-letter cycle and drops the message if nothing in the cycle was a rejection. A TTL-driven retry loop (below) is fine because the first hop is a rejection.

Retrying immediately usually hits the same transient failure again. The classic RabbitMQ pattern delays the retry with two queues: the work queue dead-letters rejected messages into a retry queue that has a message TTL and a DLX pointing back at the work queue. After the TTL the message expires and returns for another attempt. The x-death count tells the consumer how many times that has happened.

This pattern gives a fixed delay per retry queue; for growing delays you create several retry queues (5 s, 30 s, 5 min) and route by attempt. From RabbitMQ 4.3, quorum queues have native delayed retry with linear back-off: set delayed-retry-type (disabled, all, failed or returned), delayed-retry-min and optionally delayed-retry-max in milliseconds, and the delay for a returned message becomes min(min * delivery_count, max). The docs recommend it over a dead-letter cycle because it does not rewrite the message and cannot lose it. It is the better choice on 4.3 or later; the TTL+DLX loop remains the portable pattern for older versions and classic queues.

A priority queue delivers higher-priority messages first. Classic queues need x-max-priority (1 to 255, but the docs strongly recommend a small single-digit number such as 2 to 4, because each level costs resources). Quorum queues from 4.3 always support strict priorities 0 to 31 (messages without a priority count as 4) and ignore x-max-priority; before 4.3 they mapped priorities onto just two buckets. Priorities interact with prefetch: messages already delivered to a consumer cannot be overtaken, so a large prefetch weakens the effect. Use a priority queue only when one queue must mix urgencies; separate queues per urgency are usually simpler and avoid starvation questions.

Competing consumers on one queue give parallelism but no ordering: two consumers can finish messages out of order, and redelivery reorders them further. When order matters, enable single active consumer (SAC): declare the queue with x-single-active-consumer=true (Spring: QueueBuilder...singleActiveConsumer()). Many consumers may register, but the queue delivers only to one at a time; if it dies, another takes over. This gives ordered processing plus automatic failover. (SAC on streams needs a native stream client.)

One active consumer means no parallelism, which is the cost of ordering. To keep per-key order while scaling, shard the stream of messages across several queues, each with its own SAC. The consistent hash exchange plugin (rabbitmq_consistent_hash_exchange, exchange type x-consistent-hash) does the sharding: the binding key is a weight (a number as a string), and the exchange hashes the routing key (or a header named by the hash-header exchange argument) to pick one bound queue, so all messages with the same key go to the same queue.

• The hash distributes routing keys, not messages: one very hot key still lands in one queue.
• Use one binding per queue. Changing the number of queues changes the mapping, so a key may move to another queue during a resize and ordering is only guaranteed once the old queue has drained.
• This is the RabbitMQ analogue of Kafka's key-to-partition rule (page 02), implemented with queues instead of partitions.

A cluster is several RabbitMQ nodes sharing metadata (vhosts, users, exchanges, queue definitions, bindings, policies). Message data lives in queues, and only replicated queue types give high availability: quorum queues and streams. Plan on an odd number of nodes (3 or 5). Clustering is designed for a low-latency LAN. The docs say a cluster can be stretched across availability zones or data centers because quorum queues and Khepri use Raft, but that needs deliberate planning around latency and node placement; for moving messages between distant sites, Shovel and Federation are the usual tools.

• Metadata store: Mnesia was the original; Khepri (Raft-based) is fully supported from 4.0 and recommended. Both are internal; what you see is how the cluster behaves during a network partition.
• Leader placement: keep leaders balanced, otherwise one node does most of the work. Quorum queue leader placement and member reconciliation are configurable.
• Node loss: with 3 members a quorum queue keeps working after one failure. Replace the node and rebalance members; the CLI offers rabbitmq-queues add_member, grow, shrink, rebalance and quorum_status.
• Rolling upgrades: upgrade one node at a time and check rabbitmq-diagnostics check_if_node_is_quorum_critical before stopping a node, so you do not take down a majority.
• Health checks: rabbitmq-diagnostics check_running for liveness, check_alarms for resource alarms, check_for_quorum_queues_without_an_elected_leader for queue health. (check_local_alarms is deprecated and a no-op in 4.4.)

Publishers can outrun queues, disks and replication. RabbitMQ defends itself in two layers:

The memory watermark is a throttle point, not a hard cap: a node can use more than the limit. Leave headroom (RAM for the OS and file cache) and do not run a node at the edge. When an alarm is on, look for the cause, not the switch: a queue with no consumers, consumers that are slow or crashed, unacked messages piling up, or a queue type that holds too much in memory.

Enable the Prometheus plugin (rabbitmq_prometheus, port 15692, /metrics) and scrape it; the management UI (rabbitmq_management, port 15672) is for interactive inspection, and its built-in metric collection is a deprecated feature. In the rabbitmq:4-management image used for the lab both plugins were already enabled.

The default /metrics endpoint aggregates across queues to stay cheap. Per-queue series come from the detailed endpoint, where you choose metric families and optionally a vhost; avoid scraping every family from a broker with thousands of queues. Alongside metrics, log the redelivered flag and the x-death count in your consumers, and watch the dead letter queue depth: a non-empty DLQ is an alert, not a graveyard.

Queue, Exchange and Binding beans are declared on the broker by RabbitAdmin when the first connection opens. Use the builders: QueueBuilder.durable(name).quorum() sets the queue type, deliveryLimit, deadLetterExchange and singleActiveConsumer set the matching arguments, ExchangeBuilder creates exchanges, and BindingBuilder.bind(queue).to(exchange).with(key) binds. A MessageConverter bean (here JacksonJsonMessageConverter, the Jackson 3 based converter in Spring AMQP 4) is picked up by the auto-configured RabbitTemplate and by listeners.

With publisher-confirm-type: correlated each publish may carry a CorrelationData, whose getFuture() completes with a Confirm (isAck(), getReason()). With publisher-returns: true and mandatory set on the template, an unroutable message comes back as a ReturnedMessage, which is stored in the same CorrelationData. Waiting on the future per message is simple but slow; for volume, publish a batch and then wait for all futures, or register callbacks.

@RabbitListener turns a method into a consumer inside a SimpleMessageListenerContainer (the default container type; a direct container is available via spring.rabbitmq.listener.type=direct). The acknowledge mode is container-level:

Some errors are never worth retrying. Spring's default ConditionalRejectingErrorHandler rejects without requeue the failures that cannot succeed on redelivery, such as MessageConversionException, MethodArgumentNotValidException and MethodArgumentTypeMismatchException; an x-death header on such a message makes it discard instead of loop. Other exceptions follow defaultRequeueRejected.

Spring Boot can wrap the listener in stateless, in-process retry with back-off. When retries are exhausted the default recoverer, RejectAndDontRequeueRecoverer, rejects the message without requeue, so the queue's DLX (set on the queue in the topology) routes it to the DLQ. The configuration below gives 1 initial attempt plus 3 retries.

I ran this configuration against the lab broker with a listener that always throws. The handler was invoked 4 times (the first attempt plus max-retries: 3 retries) with growing pauses, then Spring logged Retries exhausted from RejectAndDontRequeueRecoverer, and the message appeared in orders.created.dlq carrying an x-death header with reason: rejected.

To keep the failure reason with the message, register a RepublishMessageRecoverer bean. Spring Boot picks a MessageRecoverer bean up automatically. It republishes the failed message to an exchange you choose with the extra headers x-exception-message, x-exception-stacktrace, x-original-exchange and x-original-routingKey, then acks the original. In the lab the message arrived in orders.dlq with x-exception-message: boom and x-original-routingKey: order.eu.created.

• Concurrency: concurrency and max-concurrency set the number of consumer threads per listener. With single active consumer only one of them receives messages.
• Observability: name your connections (spring.rabbitmq has a connection name strategy) so they are identifiable in the management UI.
• Testing: use a real broker with Testcontainers (RabbitMQContainer) rather than mocking the template; most bugs live in the topology and the acknowledgment flow.

Port 5672 is AMQP, 15672 the management UI and HTTP API (open http://localhost:15672, login guest / guest, which is acceptable only for a throwaway lab), and 15692 the Prometheus endpoint. The tool we use is **rabbitmqadmin**, the v2 command-line tool (the project is called rabbitmqadmin-ng; the binary is rabbitmqadmin, version 2.35.0 in this image). It talks to the management HTTP API. rabbitmqctl and rabbitmq-diagnostics talk to the node directly.

--non-interactive is the flag for scripts. The declare commands print nothing on success. Now publish three messages: one that matches both patterns, one that matches only order.#, and one that matches nothing.

orders.all (binding order.#) has both routed messages, orders.new (binding order.*.created) has only the first, and the unroutable one was dropped, exactly as chapter 03 predicts. Queue statistics refresh on an interval of a few seconds, so a number read immediately after an action can lag; the output above is abridged to the table rows.

The message left orders.new, passed through orders.dlx and landed in orders.dlq, with the full history in x-death. (rabbitmqadmin get messages is a polling call meant for development; use a real client in applications.)

The message waited in work.retry for its 3 second TTL, expired, was dead-lettered through the default exchange (empty name, routing key work) and arrived in work with reason: expired.

With one node every quorum queue has a single member, so quorum_status shows one leader row. A real cluster shows a leader and followers (chapter 08).

Put the four Java files and application.yml from chapter 09 in a Spring Boot 4.1 project with spring-boot-starter-amqp, set spring.rabbitmq.username and password to the lab credentials, and publish an OrderCreated through OrderPublisher. A message whose handler always throws shows 4 invocations and then arrives in orders.created.dlq; a message with a negative total is rejected on the first failure. Check the queues again:

The numbers were what the lab showed at that moment, with three queues defined; yours will match your own state. This is the same endpoint a Prometheus server would scrape.