{"id":"581c85aab5e8d043","repo":"apache/kafka","slug":"headers-cannot-be-null","errorCode":null,"errorMessage":"Headers cannot be null","messagePattern":"Headers cannot be null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecord.java","lineNumber":155,"sourceCode":"     * @param leaderEpoch Optional leader epoch of the record (may be empty for legacy record formats)\n     * @param deliveryCount Optional delivery count of the record (may be empty when deliveries not counted)\n     */\n    public ConsumerRecord(String topic,\n                          int partition,\n                          long offset,\n                          long timestamp,\n                          TimestampType timestampType,\n                          int serializedKeySize,\n                          int serializedValueSize,\n                          K key,\n                          V value,\n                          Headers headers,\n                          Optional<Integer> leaderEpoch,\n                          Optional<Short> deliveryCount) {\n        if (topic == null)\n            throw new IllegalArgumentException(\"Topic cannot be null\");\n        if (headers == null)\n            throw new IllegalArgumentException(\"Headers cannot be null\");\n\n        this.topic = topic;\n        this.partition = partition;\n        this.offset = offset;\n        this.timestamp = timestamp;\n        this.timestampType = timestampType;\n        this.serializedKeySize = serializedKeySize;\n        this.serializedValueSize = serializedValueSize;\n        this.key = key;\n        this.value = value;\n        this.headers = headers;\n        this.leaderEpoch = leaderEpoch;\n        this.deliveryCount = deliveryCount;\n    }\n\n    /**\n     * The topic this record is received from (never null)\n     */","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecord.java#L137-L173","documentation":"IllegalArgumentException thrown by the ConsumerRecord constructor when headers is null. Kafka guarantees every record carries a (possibly empty) Headers instance; null headers would cause NPEs downstream in interceptors, serializers, and metrics.","triggerScenarios":"Constructing ConsumerRecord without passing a RecordHeaders instance (commonly a 9-arg/legacy overload where headers defaulted elsewhere, or hand-built records in tests/deserializers).","commonSituations":"Test fixtures using a constructor that omits headers; custom deserializers rebuilding records with null headers; bridging from a non-Kafka source that has no header concept.","solutions":["Pass a new RecordHeaders() (empty) rather than null when no headers are needed.","If rebuilding a record inside an interceptor, propagate the original record.headers() instead of null.","Switch to a constructor overload that supplies headers explicitly."],"exampleFix":"// before\nnew ConsumerRecord<>(\"t\", 0, 0L, 0L, TimestampType.CREATE_TIME, 0, 0, k, v, null);\n\n// after\nimport org.apache.kafka.common.header.internals.RecordHeaders;\nnew ConsumerRecord<>(\"t\", 0, 0L, 0L, TimestampType.CREATE_TIME, 0, 0, k, v, new RecordHeaders());","handlingStrategy":"validation","validationCode":"// Never pass null headers; substitute an empty headers container\nHeaders safeHeaders = (headers != null) ? headers : new RecordHeaders();\nnew ConsumerRecord<>(topic, partition, offset, timestamp, timestampType, keySize, valSize, key, value, safeHeaders, leaderEpoch);","typeGuard":null,"tryCatchPattern":"try {\n    new ConsumerRecord<>(topic, partition, offset, /*...*/ key, value, headers, leaderEpoch);\n} catch (IllegalArgumentException e) {\n    if (\"Headers cannot be null\".equals(e.getMessage())) {\n        headers = new RecordHeaders();\n        // retry construction\n    }\n    throw e;\n}","preventionTips":["Always default headers to `new RecordHeaders()` rather than null when synthesizing records.","In deserializers/interceptors that forward records, never strip the headers field.","If a Record template lacks headers, add a precondition in its builder."],"tags":["consumer","consumer-record","null-check","headers","constructor"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}