Skip to content

Handle what MassTransit refuses

Warning

MassTransit 9 is commercially licensed. MassTransit 9 and later is under the MassTransit Commercial Software License Agreement (massient.com/license), a paid subscription with no exemption for testing. This format was captured from MassTransit 8, which is Apache-2.0, and the module's own .NET test programs stay on 8.x (envelope-masstransit#1). The Go module itself does not depend on MassTransit.

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

On publish

Error Cause What to do
envelope.ErrUnrepresentable, messageId is a Guid ID is not a UUID Mint a UUID for events bound for MassTransit. The format never mints one.
envelope.ErrUnrepresentable, message is a JSON value Data is not valid JSON, or DataContentType names something other than JSON Encode the payload as JSON, or publish this event with a different format.
any Validate sentinel The event is malformed Fix the event. These are the same for every format.

The refusal is on the publish path, so the caller sees it from Encode, never as a message lost in transit. The event itself is valid, which is why the error is ErrUnrepresentable and not a validation error.

w, err := f.Encode(e)

switch {
case errors.Is(err, envelope.ErrUnrepresentable):
    unrepresentable.Add(1)
case err != nil:
    invalid.Add(1)
}

On read

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

Error Cause
masstransit.ErrInvalidEnvelope The body is not a JSON object, a member appears twice, messageType is not an array of strings, headers is not an object, or a string member is another type
envelope.ErrUnrepresentable messageId is present and is not a UUID. It is never re-minted or blanked, because a new ID would defeat deduplication
envelope.ErrInvalidTime sentTime is not RFC 3339
envelope.ErrMissingAttribute No messageId, sourceAddress or messageType, or a header under an extension name with an empty value
other Validate sentinels For example a control character in a header value

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.

Unknown content

A message in none of the formats a reader was given is ErrUnrecognised, not an error of this format. A MassTransit message that arrives with a different content type, such as application/json or application/vnd.masstransit+xml, is not claimed by this format. See the reference.