{"record":{"id":"581c85aab5e8d043","repo":"apache/kafka","slug":"headers-cannot-be-null","errorCode":null,"errorMessage":"Headers cannot be null","messagePattern":"Headers cannot be null","errorType":"validation","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/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecord.java#L137-L173","documentation":"Thrown by the ConsumerRecord constructor when the headers argument is null. Kafka records always carry a Headers container (possibly empty), and downstream code assumes it can iterate or mutate headers without null checks. The constructor enforces a non-null Headers, defaulting to empty if you have none.","triggerScenarios":"Constructing a ConsumerRecord with headers=null in tests or custom adapters; an interceptor replacing a record and forgetting to carry headers forward; copying a record with a RecordHeaders-stripping mapper.","commonSituations":"Test fixtures for ConsumerRecord; bridge code from a non-Kafka message system that has no header concept; serializer/interceptor middleware that rebuilds records.","solutions":["Pass new RecordHeaders() when you have no headers, never null.","In interceptors, copy the original headers via record.headers() or a fresh RecordHeaders(copyOf(original)).","Add a helper that always supplies an empty Headers default to fixture builders."],"exampleFix":"// before\nnew ConsumerRecord<>(\"orders\", 0, 0L, key, value, null);\n\n// after\nimport org.apache.kafka.common.header.internals.RecordHeaders;\nnew ConsumerRecord<>(\"orders\", 0, 0L, key, value, new RecordHeaders());","handlingStrategy":"validation","validationCode":"Headers h = headers != null ? headers : new RecordHeaders();\nnew ConsumerRecord<>(topic, partition, offset, key, value, h);","typeGuard":"static Headers requireHeaders(Headers h) {\n    return h != null ? h : new RecordHeaders();\n}","tryCatchPattern":"try {\n    return new ConsumerRecord<>(topic, partition, offset, key, value, headers);\n} catch (IllegalArgumentException e) {\n    if (\"Headers cannot be null\".equals(e.getMessage())) {\n        return new ConsumerRecord<>(topic, partition, offset, key, value, new RecordHeaders());\n    }\n    throw e;\n}","preventionTips":["Default headers to new RecordHeaders() in any record-building helper.","In interceptors, copy original.headers() into the new record rather than passing null.","Add a unit test that exercises the no-headers code path through the helper."],"tags":["consumer","consumer-record","null-check","headers","constructor"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}