Skip to content

Find unreadable messages

A message no format in Reads can read never reaches a handler, so nothing a handler logs will tell you it existed. Two signals do. For what the adapter does with the message, see What happens to an unreadable message.

Read the counter

Bus.Stats(name) returns the subscription's ConsumerStats, and Unreadable is the number of attempts the adapter settled itself because no format could read them.

st, ok := bus.Stats("orders")
if ok && st.Unreadable > 0 {
    // a producer is writing something this subscription cannot read
}

Unreadable is outside the attempt identity: those attempts were never offered. It is how you tell a format mismatch from a handler that keeps failing.

On JetStream it counts once per attempt, so one message can add up to MaxDeliver.

Read the log

Set Settings.Logger; the default discards it. Each unreadable attempt logs at warn level:

Backend Message Attributes
Core messaging-nats: a message on the subject could not be read subscription, subject, error
JetStream messaging-nats: a message on the stream could not be read subscription, subject, error

The error is the one envelope.Read returned, and is how you tell the cases below apart. On JetStream, a Nak that failed logs messaging-nats: declining a message that could not be read failed.

Fix it

Which fix is right depends on the error:

  • Unclaimed. The producer writes a format that is not in Reads. Add that format to Reads; see Choose a wire format. Remember Reads replaces the default chain.
  • Ambiguous. Two formats in Reads both claim the message. Remove one, or fix the producer.
  • Malformed. A format claims the message and cannot decode it. The producer is writing it wrongly.