Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Reliability and Acknowledgements

Publisher Confirms and Returns

Learn how RabbitMQ publisher confirms, the mandatory flag and basic.return tell a producer whether a message was really accepted, with pika code and a runnable simulation.

When a producer calls basic_publish, nothing in plain AMQP 0-9-1 tells it what happened next. The bytes left the socket, but the broker may have crashed before writing them down, the exchange may have had no matching queue, or the queue may have refused the message. A producer that needs to know must ask for help. RabbitMQ gives you two tools: publisher confirms, which report that the broker has taken responsibility for a message, and the mandatory flag, which reports that a message could not be routed at all.

Both tools work together with the durability settings in Durability and Persistent Messages and the consumer side in Consumer Acknowledgements. Together they give you at-least-once delivery from the producer to the consumer.

The real RabbitMQ broker cannot run on this page, so the pika snippets are read-only. The runnable blocks use a small plain Python stand-in that mimics the broker's confirm and return behavior. It is a teaching model, not RabbitMQ: it has no network, no disk and no real exchanges.

Confirms in one picture

sequenceDiagram
    participant P as Producer
    participant B as Broker
    participant Q as Queue
    P->>B: confirm.select
    B-->>P: confirm.select-ok
    P->>B: basic.publish (seq 1)
    B->>Q: route and enqueue
    Q-->>B: stored (disk or quorum)
    B-->>P: basic.ack (delivery-tag 1)
    P->>B: basic.publish (seq 2, no queue matches)
    B-->>P: basic.ack (delivery-tag 2)

A confirm means the broker took responsibility for the message. It does not mean a consumer has processed it. For a message that was routed to queues, the ack arrives after every target queue accepted it: for a persistent message on a durable classic queue, after it was written to disk; for a quorum queue, after a majority of replicas stored it.

Turning confirms on

A channel is in normal mode until you send confirm.select. After that, the broker numbers every published message on that channel (1, 2, 3, ...) and answers each one with basic.ack or, rarely, basic.nack (an internal error such as a full queue refusing a message with overflow: reject-publish). Both carry the sequence number as delivery-tag and may use multiple=true to confirm everything up to that number.

With the Python client pika, the blocking connection hides most of this:

Python
import pika

connection = pika.BlockingConnection(pika.ConnectionParameters("localhost"))
channel = connection.channel()
channel.confirm_delivery()  # sends confirm.select

channel.queue_declare(queue="orders", durable=True)

try:
    channel.basic_publish(
        exchange="",
        routing_key="orders",
        body=b'{"id": 42}',
        properties=pika.BasicProperties(delivery_mode=2),
        mandatory=True,
    )
    print("broker accepted the message")
except pika.exceptions.UnroutableError:
    print("no queue received the message")
except pika.exceptions.NackError:
    print("broker refused the message")

BlockingChannel.basic_publish waits for the confirm, so each call costs one round trip. That is safe but slow. The strategies below trade simplicity for throughput.

Three confirm strategies

  1. Publish one, wait for one. Simple and slow: throughput is limited by the round-trip time. Fine for low volume.
  2. Publish a batch, then wait. Send, say, 100 messages, wait until all are confirmed, repeat. Much faster, but if a nack arrives you do not know which message in the batch failed unless you track them.
  3. Asynchronous confirms. Keep a map from sequence number to message. Register a callback for acks and nacks, remove confirmed entries, and re-publish the rest. This is the fastest and the one real services use.

With pika the asynchronous style needs SelectConnection, so most tutorials show the Java client. The idea is identical in every language: a dictionary of outstanding messages, drained by callbacks.

The mandatory flag and basic.return

Confirms alone have a surprise. If an exchange has no binding that matches, the message is simply dropped, and the broker still sends a basic.ack because it "handled" the message. To find out about unroutable messages, publish with mandatory=True. The broker then sends back basic.return (with the reply code 312 NO_ROUTE) before the ack. In pika's blocking channel, that becomes UnroutableError.

An alternative that works without client code is an alternate exchange (alternate-exchange argument or policy): unroutable messages are forwarded there, typically into a catch-all queue that someone monitors.

Python Stand-in: confirms and returns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the output carefully. order-2 was lost silently, because it was neither mandatory nor routable, yet the producer saw an ack. order-3 came back as a return first. order-4 was refused outright.

Tracking outstanding confirms

The asynchronous strategy is a pending table. The next block simulates a broker that confirms in batches with multiple=True and refuses one message, and the producer re-sends what is still pending.

Python Stand-in: pending table with multiple acks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that a retry gets a new sequence number. Sequence numbers belong to the channel, are assigned at publish time and reset when the channel closes. After a connection failure, every message still in your pending table has an unknown fate: it may or may not have reached the broker. Re-publishing it may create a duplicate, which is why consumers should be idempotent (see Dead Letter Exchanges and Retries and the projects).

Practical rules

  • Use confirms for any message you cannot afford to lose; skip them for metrics that tolerate loss.
  • Combine delivery_mode=2 (persistent), a durable queue (or a quorum queue) and confirms. Dropping any one of the three leaves a gap.
  • Use mandatory=True when a missing binding is a bug rather than a normal outcome.
  • Never mix transactions (tx.select) with confirms. Transactions are far slower and offer nothing that confirms lack.
  • Set a timeout on waiting for confirms and log what is outstanding when it fires.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a basic.ack from the broker to a publisher (confirm mode) guarantee?

    The ack means the broker accepted responsibility, for example by writing a persistent message to disk or replicating it in a quorum queue. It says nothing about consumers, and an unroutable message is also acked.
  2. 2. A message is published to an exchange with no matching binding and mandatory=false. What does the publisher see?

    Without the mandatory flag the broker silently drops unroutable messages, and in confirm mode it still acks them.
  3. 3. Why do you keep a table of unconfirmed messages when using asynchronous confirms?

    Confirms arrive later and out of band. Without the table you cannot tell which messages need a retry.
  4. 4. What does multiple=true in an ack mean?

    The broker may batch confirmations: one ack with multiple=true covers every outstanding sequence number up to that tag.

Summary

  • Confirms (confirm.select) make the broker acknowledge each published message once it took responsibility for it.
  • The mandatory flag and basic.return expose unroutable messages; alternate exchanges are a broker-side alternative.
  • Prefer asynchronous confirms with a pending table for throughput; one-at-a-time is simplest but slow.
  • Retries after failures can duplicate messages, so design consumers to tolerate them.

Next: Consumer Acknowledgements