Skip to content

Handle what NServiceBus messages get refused for

Note

NServiceBus licensing. NServiceBus is dual-licensed: the Reciprocal Public License 1.5, or Particular Software's commercial agreement (particular.net/LicenseAgreement). This format was captured from NServiceBus 10.2.9, and only the module's own .NET test programs use it. The Go module itself does not depend on NServiceBus.

Every refusal is a sentinel, so a counter can be keyed by kind. Match with errors.Is.

On send

In v0.1.0, the released version, Encode runs Validate and nothing else, so it never returns ErrUnrepresentable. From the next release it refuses one thing more: a type containing ;, which NServiceBus.EnclosedMessageTypes uses to separate types, is envelope.ErrUnrepresentable (envelope-nservicebus!4). Any ID is carried, and the payload is unconstrained. Any other refusal on send is a validation sentinel, such as ErrMissingAttribute for an event without a Source. Fix the event.

On read

Decode returns the partial event with the error. Log e.ID and e.Source.

Error Cause
nservicebus.ErrAmbiguousHeader One of NServiceBus's headers arrived under two spellings with different values, or twice under one key
envelope.ErrInvalidTime NServiceBus.TimeSent is not yyyy-MM-dd HH:mm:ss:ffffff Z: an ISO 8601 time, a signed microsecond or five digits are all refused
envelope.ErrMissingAttribute No NServiceBus.EnclosedMessageTypes, no NServiceBus.OriginatingEndpoint, or a lower-case header with an empty value
other Validate sentinels For example a control character in a header value
switch {
case errors.Is(err, nservicebus.ErrAmbiguousHeader):
    ambiguous.Add(1)
case errors.Is(err, envelope.ErrMissingAttribute):
    missing.Add(1)
case err != nil:
    other.Add(1)
}

Do not retry. Each is deterministic, and the same bytes will be refused the same way. Fix the producer, or replay from the producer's own record.

A message from a send-only or non-NServiceBus producer

The format needs NServiceBus.OriginatingEndpoint and NServiceBus.EnclosedMessageTypes. A message that has a NServiceBus.MessageId but not those is claimed and then refused as ErrMissingAttribute, with its ID in the partial event.

Unknown content

A message with no NServiceBus.MessageId is not claimed by this format. In a chain with nothing else claiming it, it is ErrUnrecognised. See the reference.