Skip to content

Find messages no format could read

A message that no format in Settings.Reads can read never reaches a handler, so a handler's logs will not show it. What the adapter does with one is in Delivery, settlement and flow control. This page is how to notice one and what to do next.

Watch the counter

st, ok := bus.Stats("orders")
if ok && st.Unreadable > 0 {
    // messages this subscription's formats cannot read are arriving
}

Unreadable counts attempts, not messages. Under AtLeastOnce one unreadable message is declined at each delivery until it dead-letters, so it adds MaxDeliver. Under AtMostOnce it adds one. The adapter does not count these in Accepted or Exhausted.

That is how to tell a format mismatch from a handler that keeps failing: a failing handler raises Exhausted, an unreadable message raises Unreadable and leaves Exhausted alone.

Read the log

Give Settings.Logger a handler. Unset, it discards. Each unreadable delivery logs at warn level:

messaging-amqp: a message on the queue could not be read  subscription=orders error=...

The error is envelope.Read's: no format claimed the message, more than one did, or one claimed it and could not decode it. It is the first thing to read.

Common causes

  • A producer writing a format you do not read. Add it to Settings.Reads. See Choose a wire format.
  • A producer that sends its body as an amqp-value or amqp-sequence section. The adapter reads only data sections, so the body arrives empty. See Wire format.
  • Two formats claiming one message. The chain refuses to guess between them. Narrow Reads.
  • A CloudEvents message missing a required attribute. One format claims it and cannot decode it.

Recover what dead-lettered

Under AtLeastOnce an unreadable message is rejected on its last attempt and the broker moves it to the address's dead-letter address. Read it from there with any AMQP client, fix the reader chain, and publish it again. Under AtMostOnce it was accepted and dropped, and there is nothing to recover. If you cannot lose them, do not use AtMostOnce on an address that foreign producers write to.

When you publish it again, remember the broker's duplicate-id cache: a message with the same Source and ID as one the broker has already seen is accepted and dropped. See Wire format.