Kafka Quick Reference

A compact lookup for the confluent-kafka producer and consumer, config keys, topic settings, the CLI, and common errors.

Before you use this reference

This page is a lookup, not a tutorial. The explanations live in Kafka Fundamentals, Topics, Partitions, and Offsets, Running Kafka Locally, Producing Messages with Python, and Consuming Messages with Python. The client library is confluent-kafka.

Connect from where#

FromBootstrap address
Host machine127.0.0.1:9092
Another containerkafka:29092
Kafka UIhttp://localhost:8085
CLI inside the broker containerlocalhost:29092

Producer skeleton#

Python
import jsonfrom confluent_kafka import Producer
producer = Producer({    "bootstrap.servers": "localhost:9092",    "enable.idempotence": True,    "acks": "all",    "linger.ms": 10,})

def on_delivery(err, msg):    if err is not None:        print(f"delivery failed: {err}")

for event in events:    producer.produce(        topic="order-events",        key=str(event["customer_id"]).encode("utf-8"),        value=json.dumps(event).encode("utf-8"),        on_delivery=on_delivery,    )    producer.poll(0)
remaining = producer.flush(timeout=10)

Consumer skeleton#

Python
import jsonfrom confluent_kafka import Consumer
consumer = Consumer({    "bootstrap.servers": "localhost:9092",    "group.id": "warehouse-sink",    "auto.offset.reset": "earliest",    "enable.auto.commit": False,})consumer.subscribe(["order-events"])
batch = []try:    while True:        msg = consumer.poll(timeout=1.0)        if msg is None:            continue        if msg.error():            continue
        try:            event = json.loads(msg.value().decode("utf-8"))        except ValueError:            continue  # route to a dead-letter destination instead
        batch.append(event)        if len(batch) >= 100:            write_batch(batch)                    # write first            consumer.commit(asynchronous=False)   # then commit            batch.clear()except KeyboardInterrupt:    passfinally:    if batch:        write_batch(batch)        consumer.commit(asynchronous=False)    consumer.close()

Producer config keys#

KeyMeaning
bootstrap.serversBroker address(es), comma-separated
enable.idempotenceTrue: retries do not create duplicate appends
acksall (in-sync replicas) / 1 (leader) / 0 (fire and forget)
linger.msWait this long to batch more records per request
batch.sizeMax bytes per partition batch
compression.typenone / lz4 / zstd
queue.buffering.max.messagesIn-memory send-queue size; produce() raises BufferError when full
message.max.bytesMax size of a single record

Consumer config keys#

KeyMeaning
bootstrap.serversBroker address(es)
group.idConsumer group name (required)
auto.offset.resetearliest / latest; used only when no committed offset exists
enable.auto.commitTrue commits on a timer; False to commit manually
auto.commit.interval.msHow often auto-commit runs (default 5000)
max.poll.interval.msMax gap between poll() calls before a rebalance (default 300000)
session.timeout.msHow long the group waits before declaring a member dead
fetch.min.bytes / fetch.max.wait.msBatch reads from the broker

Message object#

MethodReturns
msg.value() / msg.key()Payload / key as bytes (or None)
msg.topic()Topic name
msg.partition()Partition number
msg.offset()Offset in the partition
msg.timestamp()(type, ms) tuple
msg.headers()List of (key, bytes) or None
msg.error()None, or a KafkaError to handle

Topic config keys#

KeyMeaning
retention.msDelete records older than this (e.g. 604800000 = 7 days)
retention.bytesDelete oldest segments once a partition exceeds this size
cleanup.policydelete (age/size) or compact (keep latest value per key)
partitionsNumber of partitions (increase only)
replication.factorCopies per partition (1 locally)
min.insync.replicasWith acks=all, minimum replicas that must ack a write

kafka-topics CLI#

Bash
kafka-topics --bootstrap-server localhost:29092 --listkafka-topics --bootstrap-server localhost:29092 \  --create --topic order-events --partitions 3 --replication-factor 1kafka-topics --bootstrap-server localhost:29092 --describe --topic order-eventskafka-topics --bootstrap-server localhost:29092 --alter --topic order-events --partitions 6

kafka-configs CLI#

Bash
kafka-configs --bootstrap-server localhost:29092 \  --alter --entity-type topics --entity-name order-events \  --add-config retention.ms=259200000
kafka-configs --bootstrap-server localhost:29092 \  --describe --entity-type topics --entity-name order-events

kafka-consumer-groups CLI#

Bash
kafka-consumer-groups --bootstrap-server localhost:29092 --listkafka-consumer-groups --bootstrap-server localhost:29092 --describe --group warehouse-sinkkafka-consumer-groups --bootstrap-server localhost:29092 \  --group warehouse-sink --topic order-events \  --reset-offsets --to-earliest --execute

--describe shows CURRENT-OFFSET, LOG-END-OFFSET, and LAG per partition.

Console tools#

Bash
kafka-console-producer --bootstrap-server localhost:29092 --topic order-eventskafka-console-consumer --bootstrap-server localhost:29092 --topic order-events --from-beginning

JSON message contract skeleton#

JavaScript
{  "order_id": 101,            // business key: unique, used for de-duplication  "customer_id": 1,           // partition key: keeps a customer's events ordered  "created_at": "2026-01-04T09:12:00",  "amount": 1200.0,  "schema_version": 1         // bump on an incompatible change}

Rules: additive changes only without coordination; document required fields; version explicitly for incompatible changes.

Common errors#

Error / symptomCauseFix
BufferError: Local: Queue fullProducing faster than the client sendspoll() more often, raise queue.buffering.max.messages, or slow down
"Message timed out" in a delivery reportBroker unreachable or wrong advertised listenerCheck bootstrap.servers and listener config for your location
MSG_SIZE_TOO_LARGERecord exceeds message.max.bytesShrink payload, store blob elsewhere, or raise the limit
Consumer reads nothingCommitted offset at the end, or auto.offset.reset=latest on a fresh groupNew group.id, or --reset-offsets --to-earliest
Frequent rebalancesProcessing exceeds max.poll.interval.ms between pollsSmaller batches / faster work / raise the interval
Connects then hangsUsed localhost from a container, or kafka:29092 from the hostMatch the address to where the client runs

See also#