apache/kafka · error · IllegalArgumentException

Topic cannot be null

Error message

Topic cannot be null

What it means

Thrown by the ConsumerRecord constructor when the topic argument is null. A ConsumerRecord models a single record from a specific topic-partition, so a null topic would make the record unusable for partition lookup, offset tracking, and rebalance accounting. The check happens at construction so the bad value cannot propagate.

Solutions

1. Pass a non-null topic string when constructing ConsumerRecord (use the real topic name from the source).
2. In interceptors/wrappers, propagate the original record.topic() rather than null.
3. In tests, use a literal topic constant matching the partition you also set.

Example fix

// before
new ConsumerRecord<>(null, 0, 0L, key, value);

// after
new ConsumerRecord<>("orders", 0, 0L, key, value);

if (topic == null) throw new IllegalArgumentException("topic must be non-null when building ConsumerRecord");
new ConsumerRecord<>(topic, partition, offset, key, value, new RecordHeaders());

static String requireTopic(String t) {
    return Objects.requireNonNull(t, "ConsumerRecord topic");
}

try {
    return new ConsumerRecord<>(topic, partition, offset, key, value, headers);
} catch (IllegalArgumentException e) {
    if ("Topic cannot be null".equals(e.getMessage())) {
        // fall back to a safe default topic or rethrow as a domain error
    }
    throw e;
}

When it happens

Trigger: Constructing a ConsumerRecord directly (typically in tests or in a custom deserializer/interceptor) with topic=null; deserializing from a source that lost its topic field; mocking records without setting topic; an interceptor rewriting records and passing null topic.

Common situations: Unit tests building ConsumerRecord fixtures; custom plugins that wrap/replace records; consumers reading from non-Kafka sources being adapted into ConsumerRecord; serializer bugs that drop topic context.

Related errors

• Headers cannot be null
• RebalanceListener cannot be null
• Topic must be non-null.
• Cannot add records for a partition that is not assigned to…
• Cannot lose partitions that are not currently assigned

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/fda0903711042f33. Report an issue: GitHub.

Appendix: source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecord.java:153

     * @param value The record contents
     * @param headers The headers of the record
     * @param leaderEpoch Optional leader epoch of the record (may be empty for legacy record formats)
     * @param deliveryCount Optional delivery count of the record (may be empty when deliveries not counted)
     */
    public ConsumerRecord(String topic,
                          int partition,
                          long offset,
                          long timestamp,
                          TimestampType timestampType,
                          int serializedKeySize,
                          int serializedValueSize,
                          K key,
                          V value,
                          Headers headers,
                          Optional<Integer> leaderEpoch,
                          Optional<Short> deliveryCount) {
        if (topic == null)
            throw new IllegalArgumentException("Topic cannot be null");
        if (headers == null)
            throw new IllegalArgumentException("Headers cannot be null");

        this.topic = topic;
        this.partition = partition;
        this.offset = offset;
        this.timestamp = timestamp;
        this.timestampType = timestampType;
        this.serializedKeySize = serializedKeySize;
        this.serializedValueSize = serializedValueSize;
        this.key = key;
        this.value = value;
        this.headers = headers;
        this.leaderEpoch = leaderEpoch;
        this.deliveryCount = deliveryCount;
    }

    /**

View on GitHub (pinned to 996fb4585a)