Skip to content

What happens to an unreadable message

A message arrives from a producer that is not this bus, in a shape this bus does not read. The adapter reads every received message through the Reads chain with envelope.Read. A message is unreadable when envelope.Read refuses it, which covers three cases:

  • Unclaimed: no format in the chain claims it.
  • Ambiguous: two formats both claim it. The reader refuses to guess between them.
  • Malformed: a format claims it and cannot decode it.

An unreadable message never becomes a Delivery, so no handler sees it. The adapter counts it in SourceStats.Unreadable, once per attempt, and logs it at warn. It is not counted in Accepted, Exhausted or Refused, because the bus never offered it. The design is spec 0015, and the core's side of the contract is in the backend contract.

Core: dropped

Core NATS delivers at most once and keeps nothing, so the adapter drops the message. The warning reads messaging-nats: a message on the subject could not be read, with the attributes subscription, subject and error.

If the unreadable message was a request, no reply is sent, and the requester waits until its own deadline.

JetStream: declined at once

The adapter declines the message with Nak straight away, which is the call a declined delivery gets. It spends the message's attempts quickly, with no delay between them, and the server stops offering it after MaxDeliver. The warning reads messaging-nats: a message on the stream could not be read, with the same attributes, once for each attempt.

Three details:

  • The last attempt is not Exhausted. The message was never offered, so it sits outside every identity. The Nak on the last attempt is the same call, and the server simply stops.
  • The message stays in the stream. The adapter does not delete it or move it. Retention is the stream's.
  • A failed Nak is logged, not retried. The warning reads messaging-nats: declining a message that could not be read failed, and the server offers the message again after AckWait.

A message pulled while the source is retiring is held and declined only after the drain has finished, because a Nak while a pull request is outstanding is a redelivery straight back into the same iterator. It is still not counted Exhausted.

What it costs

Every unreadable message spends its consumer's attempts, one Nak after another. A stream with a producer writing a shape this bus does not read therefore keeps the consumer busy with that producer's messages until each has run out of attempts. Find unreadable messages says how to see it.

Source: (*source).handle in source.go; read, decline, pull and returnDrained in jetsource.go; the tests TestAMessageNoFormatCanReadIsCountedUnreadable and TestAnUnreadableMessageDrainedAtRetirementIsNotExhausted.