Every data processing system will eventually receive a record it cannot handle. A missing required field, an unexpected data type, a payload that exceeds size limits, a downstream service that rejects the record with a non-transient error. What happens to that record determines whether your system is reliable or merely operational.
A dead letter queue (DLQ) is the mechanism that handles unprocessable records without stopping the rest of the pipeline. Instead of retrying indefinitely or dropping the record silently, the system writes the failed record to the DLQ and continues processing the next one.
This guide covers what a DLQ needs to contain, how to implement one, when to use it, and how to monitor it.
What Goes in a Dead Letter Queue
A DLQ entry needs enough information to answer three questions later:
- What was the original record?
- Why did it fail?
- At which stage did it fail?
At minimum, each DLQ entry should contain:
- The full original record payload (not just an ID reference)
- The error message or exception that caused the failure
- The stage name where the failure occurred
- A timestamp
- A correlation ID (run ID, batch ID, or similar)
- A failure count (to distinguish first-time failures from repeated failures)
The original payload must be stored in full. A reference to a source record is not sufficient because the source may change or the record may be deleted by the time you investigate. The DLQ is a point-in-time snapshot of the failed state.
Designing the DLQ Storage
DLQ storage depends on the pipeline architecture.
For message-queue-based pipelines: RabbitMQ has native DLQ support through dead letter exchanges. Messages that exceed their retry count or their time-to-live are automatically routed to a designated DLQ exchange. Apache Kafka does not have native DLQ semantics, but the standard pattern is to write failed records to a dedicated topic (<topic>-dlq by convention) and include the failure metadata in the record headers.
For database-backed pipelines: A dedicated table with columns for the original record JSON, error message, stage, timestamp, and failure count works well. Add an index on stage and timestamp to support common query patterns.
For cloud-managed queues: Amazon SQS has a built-in DLQ mechanism where a source queue is configured with a redrive policy that specifies a maximum receive count and a DLQ target. Google Cloud Pub/Sub provides a similar dead letter policy.
Implementation: The Retry-Then-DLQ Pattern
The standard pattern is to attempt processing a fixed number of times before routing to the DLQ:
MAX_RETRIES = 3
def process_record(record, retry_count=0):
try:
result = transform_and_load(record)
return result
except TransientError as e:
if retry_count < MAX_RETRIES:
time.sleep(backoff_delay(retry_count))
return process_record(record, retry_count + 1)
else:
write_to_dlq(record, str(e), stage="transform_and_load", retry_count=retry_count)
except PermanentError as e:
# Non-transient errors go directly to DLQ without retry
write_to_dlq(record, str(e), stage="transform_and_load", retry_count=0)
Distinguishing transient errors (network timeouts, rate limits, temporary service unavailability) from permanent errors (schema validation failures, type errors, records that fail business logic) is important. Retrying permanent errors wastes time and fills the DLQ with duplicate entries.
def write_to_dlq(record, error_message, stage, retry_count):
dlq_entry = {
"payload": record,
"error": error_message,
"stage": stage,
"timestamp": datetime.utcnow().isoformat(),
"retry_count": retry_count,
"run_id": current_run_id()
}
dlq_store.write(dlq_entry)
Monitoring the DLQ
A DLQ that no one watches provides less value than no DLQ at all. Key metrics to track:
DLQ entry count per run: A non-zero count indicates records failed processing. The absolute count tells you the scope of the issue. Zero for many runs followed by a spike indicates a schema change or upstream data quality regression.
DLQ growth rate: DLQ entries accumulating faster than they are being resolved indicate a systematic issue. A DLQ that grows by 500 records per run without any remediation action will overwhelm your ability to investigate individually.
Top error messages: Group DLQ entries by error message. If 90% of failures share the same error, one fix resolves 90% of the backlog. If failures are evenly distributed across dozens of error types, the issue is systemic.
For broader pipeline observability beyond DLQ monitoring, the guide on monitoring data integration pipelines in production covers record counts, alerting, and end-to-end reconciliation.
The DLQ Replay Workflow
A DLQ only provides value if you can act on its contents. The replay workflow is:
- Investigate DLQ entries to identify the failure pattern.
- Fix the underlying issue (schema validation rule, transformation logic, downstream service configuration).
- Re-queue DLQ entries back to the main processing queue.
- Confirm records process successfully on the second pass.
The replay step should be treated as a controlled operation, not a bulk re-queue. Before replaying the full DLQ, replay a sample of entries and confirm they process correctly.
Photo by Keysi Estrada on Pexels
DLQ Policies: When to Expire Records
Not every failed record should be kept indefinitely. A DLQ retention policy prevents unbounded growth:
- For records that fail due to upstream data quality: retain until the source issue is resolved and a remediation run is possible.
- For records that fail due to pipeline logic errors: retain until the fix is deployed and replayed.
- For records past a maximum age (typically 30-90 days): log a summary and archive or discard. Replaying records that are too old often produces incorrect results because the system state has changed.
The policy should be documented so the team knows what guarantees the DLQ provides.
Distinguishing Transient From Permanent Errors
The effectiveness of a DLQ depends heavily on correctly classifying errors as transient (retry-able) or permanent (send immediately to DLQ). Misclassifying a permanent error as transient wastes retries and delays DLQ capture. Misclassifying a transient error as permanent loses records that could have been recovered.
Transient errors are conditions expected to resolve on their own: network timeouts, rate limit responses (HTTP 429), temporary service unavailability (HTTP 503), connection resets. These should be retried with exponential backoff.
Permanent errors are conditions that will not resolve without a code or data change: schema validation failures, type conversion errors, business logic violations, records that exceed destination size limits, duplicate key violations on non-idempotent loads. These should go directly to the DLQ without retry.
Some errors are ambiguous. An HTTP 500 from a downstream API could indicate a transient server error or a bug triggered by the specific record. For ambiguous errors, retry once or twice with a short backoff. If the error persists, treat it as permanent and route to DLQ.
Alerting on DLQ Patterns
A DLQ that accumulates records without triggering alerts is almost as bad as no DLQ. Alert thresholds for DLQ monitoring:
Absolute threshold: More than N new DLQ entries in the last pipeline run. The value of N depends on your expected error rate baseline. For a pipeline that historically has zero DLQ entries, any DLQ entry should trigger an investigation.
Growth rate threshold: DLQ depth increasing by more than X% per day. A gradually growing DLQ indicates a systemic issue that is not being resolved.
Error pattern concentration: If 80% of DLQ entries share the same error message, that is a systematic failure worth immediate attention. Group DLQ entries by error message and alert when any single error type exceeds a threshold.
For the broader monitoring architecture that DLQ alerting fits into, including record-level accounting, end-to-end reconciliation, and alert calibration, see the guide on monitoring data integration pipelines in production.
137Foundry designs data integration architectures with built-in reliability patterns including dead letter queues, idempotency, and end-to-end reconciliation. The data integration service covers both new builds and reliability improvements to existing pipelines.