Dead-letter & tracing

Last updated: October 31, 2026

Two cross-cutting behaviours every SDK shares, both designed so a failure or a trace crosses language boundaries unchanged: dead-lettering (where a message goes when it can’t be processed) and trace propagation (how one correlation id ties a whole chain of work together). Both are part of the wire contract and neither touches the frozen schema_version: 1.

Dead-letter queue: <queue>.dlq

When a message exhausts its retries, or arrives with a URN no consumer handles (and the unknown-URN strategy is dead_letter), it is republished to a dead-letter queue rather than dropped. The convention is the source queue name plus a .dlq suffix — a message that failed on orders lands on orders.dlq. Because the dead-lettered message is still the canonical envelope, any SDK can read the DLQ and triage it, regardless of which language produced or failed the message.

The default suffix is .dlq across the ecosystem (e.g. Laravel’s dead_letter.suffix, Go’s WithDeadLetterSuffix); Amazon SQS is the exception, because an SQS queue name cannot contain a dot: there the convention is -dlq (orders-dlq; FIFO: orders-dlq.fifo), and the Go, Python and Laravel SQS transports use it by default (an explicit suffix or queue name still wins; on a FIFO queue a suffix goes before .fifo, so orders.fifo + -dlq is orders-dlq.fifo). Dead-lettering is opt-in: enable it per SDK (dead_letter: true in Python, WithDeadLetter(true) in Go, maxTries + the DLQ path in the Node transports, the dead_letter block in Laravel config). With it disabled, a terminally failed message is dropped instead.

The additive dead_letter block

A message sitting on a DLQ carries one extra, optional top-level field, dead_letter, describing why it failed. It appears only on DLQ messages — never on a normal queue — and is purely additive, so the envelope stays frozen at schema_version: 1. Normal consumers ignore it; a triage tool reads it.

{
  "job": "urn:babel:orders:created",
  "trace_id": "7b3f9c2a-e41d-4f88-9b2a-1c0d5e6f7a8b",
  "data": { "order_id": 1042 },
  "meta": {
    "id": "f1e2d3c4-b5a6-4789-90ab-cdef01234567",
    "queue": "orders",
    "lang": "php",
    "schema_version": 1,
    "created_at": 1749132727000
  },
  "attempts": 3,
  "dead_letter": {
    "reason": "failed",
    "error": "Payment gateway timeout",
    "exception": "App\\Exceptions\\GatewayTimeout",
    "failed_at": 1749132730000,
    "original_queue": "orders",
    "attempts": 3,
    "lang": "php"
  }
}

The original envelope is preserved unchanged inside the dead-lettered message — job, trace_id, data, meta and attempts are exactly what they were, so the DLQ message is a faithful record of what failed and where it came from (original_queue). Every SDK exposes a helper that wraps an envelope in this block and returns a copy, leaving the input untouched:

dead_letter keys are descriptive, not contract envelope fields. This block is a diagnostic side-channel that exists only on the DLQ. Do not confuse it with the frozen envelope — and note the forbidden top-level/meta fields (timestamp, meta.max_retries, meta.source, meta.ts) still never appear, on the DLQ or anywhere else. See forbidden fields.

Not every DLQ record is a canonical envelope

A reader of <queue>.dlq must not assume the dead_letter block is there. Three shapes can share a DLQ, and a triage tool tells them apart without guessing:

A version-gated message is never decoded, so there is nothing to wrap: the raw body is what a future, compatible consumer or a redrive tool needs. It is written on Pulsar, Artemis, SQS and Azure Service Bus, on the first delivery, and only when the BabelQueue DLQ is on (or the dead_letter strategy has a writable DLQ). The original is acknowledged after the DLQ write succeeds; a failed write leaves it unsettled, so it is redelivered and the write is retried.

One exception is documented, not accidental. With the BabelQueue DLQ disabled, Laravel’s babelqueue-* connections fail a poison body or an exhausted job into Laravel’s own failed_jobs table. The Laravel SQS and Artemis drivers also keep their own version-gate path: with the DLQ enabled they publish a version-gated delivery as a stub envelope with a dead_letter block (reason: "poison"), not as the raw body, so a reader must not expect the original bytes there; with it disabled they throw, and Laravel’s retry and then failed_jobs take it.

Broker-native dead-lettering

Some brokers have a native dead-letter mechanism, and the bindings use it alongside the cross-language <queue>.dlq convention rather than instead of it:

• Redis / RabbitMQ / Go’s runtime — the SDK republishes the wrapped envelope to <queue>.dlq.
• Apache Kafka — no native DLQ, so the SDK owns it: terminal failures go to <topic>.dlq with the dead_letter block (after the tiered <topic>.retry.<n> topics). The consumed record’s key is carried onto the DLQ record. See the Kafka binding.
• Apache Pulsar — a native DeadLetterPolicy exists, but it is a client-side setting the SDKs do not apply: the bound is the SDK’s own max-attempts (default 3). When it is used up the SDK writes the cross-language <queue>.dlq (opt-in; with dead-lettering off the message is acknowledged, dropped and logged), so other SDKs can triage. That holds for the Go and Python runtimes, the Java, .NET and Node consumers (dead_letter.attempts is the counted value, 3 with the default) and the PHP Consume\Dispatcher given a DeadLetterPublisher; the Dispatcher writes <queue>.dlq with the queue taken from the consumer’s topic and never default.dlq. A poison body is recorded there without retry. A retry is a re-publish with bq-attempts + 1, so the cap holds on every subscription type. The bare PHP PulsarConsumer leaves it to the handler. A message with an unsupported bq-schema-version is settled on its first delivery, never retried: acknowledged and dropped without a DLQ, otherwise written to <queue>.dlq as the raw body. See the Pulsar binding.
• ActiveMQ Artemis — a native dead-letter address exists, and the binding also writes the cross-language <queue>.dlq so other SDKs can triage. A poison body is recorded there as the poison record (Java, .NET and Node used to forward the raw bytes), and a message with an unsupported bq_schema_version is written as the raw body; with no DLQ configured both are acknowledged, dropped and logged.
• Amazon SQS / Azure Service Bus — the SDK-driven dead-letter sends the annotated envelope to the cross-language DLQ (opt-in): <queue>.dlq on Azure Service Bus and <queue>-dlq on SQS (FIFO: <queue>-dlq.fifo), because an SQS queue name cannot contain a dot. The broker’s own facility (SQS RedrivePolicy, ASB $DeadLetterQueue) is a complementary safety net you configure on the broker: it moves the message verbatim, so it carries no dead_letter block. The envelope on them is still canonical. When the BabelQueue DLQ is configured, a poison body (as the poison record) and a version-gated message (as the raw body) go to that DLQ on their first delivery. When it is off, the broker’s facility is the settle for those two cases: the SDK does not delete the SQS message (the RedrivePolicy takes it after maxReceiveCount) and Azure Service Bus abandons it until MaxDeliveryCount or dead-letters it natively. Nothing is silently dropped.

See the broker bindings for the per-broker detail.

Trace propagation (trace_id)

trace_id is a required, immutable id that the first producer in a chain mints (a v4 UUID), and that every SDK then preserves and forwards unchanged across every hop — the fourth golden rule (GR-4). It is how you follow one unit of work as it fans out across services and languages.

Producers mint only UUIDs, but a trace_id that is not a UUID (from a non-BabelQueue producer or a hand-built message) is carried on exactly the same way: preserved byte for byte, never rejected, never regenerated. See a trace_id that is not a UUID.

The rule, straight from the consumer rules: when a consumer produces a downstream message while handling one, it copies the inbound trace_id onto the new envelope and mints a new meta.id. Do not conflate the two — see id vs trace_id:

Continuing a trace, per SDK

Every producer API takes an optional inbound trace id; pass it to continue the chain, omit it to start a fresh one:

# Python — reuse the inbound trace_id on a downstream message
app.publish("urn:babel:shipping:requested", {"order_id": 1042}, trace_id=inbound["trace_id"])

// Go — WithTraceID continues the trace; omit it to mint a new one
env, _ := babelqueue.Make(
    "urn:babel:shipping:requested",
    map[string]any{"order_id": 1042},
    babelqueue.WithTraceID(inbound.TraceID),
)

// Node — pass traceId in the options
const env = EnvelopeCodec.make(
  "urn:babel:shipping:requested",
  { order_id: 1042 },
  { traceId: inbound.trace_id },
);

// Java — pass the inbound trace id (or null to mint a fresh one)
Envelope env = EnvelopeCodec.make(
    "urn:babel:shipping:requested", Map.of("order_id", 1042L), "orders", inbound.traceId());

// .NET — pass traceId to continue the trace
var env = EnvelopeCodec.Make(
    "urn:babel:shipping:requested",
    new Dictionary<string, object?> { ["order_id"] = 1042L },
    queue: "orders", traceId: inbound.TraceId);

The framework adapters automate this so you never plumb it by hand: Laravel hands the handler the $traceId and reuses it; Symfony’s babelqueue.messenger.trace_middleware attaches a BabelTraceStamp so any message a handler dispatches inherits the inbound trace_id.

Tracing through the DLQ

Because the dead-lettered message preserves the original envelope unchanged, trace_id survives dead-lettering too. A message that failed three hops into a chain still carries the chain’s trace_id on orders.dlq, so you can correlate the failure back to the original producer and every service that touched it — in any language.

To count dead-letters rather than trace them, every SDK can feed the babelqueue.dlq.messages metric from the same write points; see What babelqueue.dlq.messages counts. To find the failing chain in your application logs, see Log correlation.

In one line

A failure becomes a canonical envelope on <queue>.dlq with an additive dead_letter block any SDK can read, and one trace_id — minted once, forwarded unchanged — ties the whole chain together, DLQ included. Neither mechanism changes the frozen schema_version: 1.

Back to Broker bindings · or the broker setup recipes.