Dead Letter Queues & Triage

Overview

A dead letter queue (DLQ) is a topic where records go when a pipeline has given up on processing them. Kafka Connect sink connectors have built-in dead letter queue settings, and Kafka Streams has errors.dead.letter.queue.topic.name; with the plain consumer API you would build it yourself. In Connect, errors.tolerance defaults to none, which fails the task immediately on an error, and all skips problem records, so the dead letter queue and the log become the record of what failed. The error context, meaning topic, partition and offset, and the context headers when errors.deadletterqueue.context.headers.enable is true, tells you where a record came from. The triage steps in the tip below are team practice, not Apache guidance.

Analogy

Key configuration

# A minimal dead letter queue configuration:
errors.tolerance=all
errors.deadletterqueue.topic.name=dlq.<connector-name>
errors.deadletterqueue.context.headers.enable=true
errors.log.enable=true
# errors.log.include.messages=true also logs record keys, values and headers
# and may log sensitive information; it defaults to false

Production tip

Sources

• Kafka Connect user guide (4.2 documentation) (opens in a new tab)
• Kafka Connect configs (4.2 documentation) (opens in a new tab)
• Kafka Streams configs (4.2 documentation) (opens in a new tab)

Checked against Kafka 4.2 documentation on Oct 2026. Draft: not yet reviewed by a Kafka specialist. Releases move on, so confirm against the current documentation before you act on a number.