Dead-Letter Topics

Dead-Letter Topics Overview

Dead-Letter Topics is a building block you will reach for often in Apache Kafka. It keeps related logic together and makes your intent obvious to reviewers and future maintainers.

When you learn dead-letter topics properly, you avoid the guesswork that leads to bugs and rework. The example below shows the shape you will use in most real Apache Kafka projects.

import { Kafka } from 'kafkajs';

const kafka = new Kafka({ clientId: 'admin', brokers: ['localhost:9092'] });
const admin = kafka.admin();

await admin.connect();
await admin.createTopics({
  topics: [{ topic: 'orders', numPartitions: 6, replicationFactor: 3 }],
});
await admin.disconnect();

The admin client creates topics with a chosen partition count and replication factor.

Dead-Letter Topics Example

import { Kafka } from 'kafkajs';

const kafka = new Kafka({ clientId: 'app', brokers: ['localhost:9092'] });
const producer = kafka.producer();
const consumer = kafka.consumer({ groupId: 'group' });

• Start from a minimal Dead-Letter Topics example and grow it only as needed.
• Keep configuration explicit so Dead-Letter Topics behaves the same in every environment.
• Name things clearly so teammates understand your Dead-Letter Topics at a glance.
• Add tests around Dead-Letter Topics early to lock in expected behaviour.

Apache Kafka Cheatsheet

Handy KafkaJS reference related to dead-letter topics.

How Dead-Letter Topics Works in Apache Kafka

Dead-Letter Topics builds on Kafka's log-based design, where producers append events to partitioned topics and consumer groups read them independently, tracking their own offsets.

The admin client creates topics with a chosen partition count and replication factor.

• Topics are split into partitions for parallelism and ordering per key.
• Producers choose a partition, usually by message key.
• Consumer groups share partitions so work scales horizontally.
• Offsets record how far each group has read.

Practical Guidance for Dead-Letter Topics

In production, dead-letter topics needs attention to delivery guarantees, retries, and observability. Make handlers idempotent and monitor consumer lag closely.

Common Mistakes

• Copying dead-letter topics snippets without understanding what each line does.
• Skipping error handling and edge cases when wiring up dead-letter topics.
• Leaving dead-letter topics untested, so regressions slip into production.
• Over-engineering dead-letter topics before you actually need the extra flexibility.

Key Takeaways

• Dead-Letter Topics is a core part of working effectively with Apache Kafka.
• Start small and keep dead-letter topics focused on a single responsibility.
• Apply consistent patterns so dead-letter topics scales across your project.
• Test and document dead-letter topics to keep it maintainable over time.