{"id":"ae9889e0fef2095e","repo":"apache/kafka","slug":"invalid-null-header-key-found-in-headers","errorCode":null,"errorMessage":"Invalid null header key found in headers","messagePattern":"Invalid null header key found in headers","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/record/internal/DefaultRecord.java","lineNumber":207,"sourceCode":"        }\n\n        if (value == null) {\n            ByteUtils.writeVarint(-1, out);\n        } else {\n            int valueSize = value.remaining();\n            ByteUtils.writeVarint(valueSize, out);\n            Utils.writeTo(out, value, valueSize);\n        }\n\n        if (headers == null)\n            throw new IllegalArgumentException(\"Headers cannot be null\");\n\n        ByteUtils.writeVarint(headers.length, out);\n\n        for (Header header : headers) {\n            String headerKey = header.key();\n            if (headerKey == null)\n                throw new IllegalArgumentException(\"Invalid null header key found in headers\");\n\n            byte[] utf8Bytes = Utils.utf8(headerKey);\n            ByteUtils.writeVarint(utf8Bytes.length, out);\n            out.write(utf8Bytes);\n\n            byte[] headerValue = header.value();\n            if (headerValue == null) {\n                ByteUtils.writeVarint(-1, out);\n            } else {\n                ByteUtils.writeVarint(headerValue.length, out);\n                out.write(headerValue);\n            }\n        }\n\n        return ByteUtils.sizeOfVarint(sizeInBytes) + sizeInBytes;\n    }\n\n    @Override","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/record/internal/DefaultRecord.java#L189-L225","documentation":"DefaultRecord.writeTo (line 207) and sizeOf reject any Header whose key() returns null. The wire format requires a length-prefixed UTF-8 key for every header, so a null key is a programmer error, not a valid 'no key' state.","triggerScenarios":"Constructing new RecordHeader(null, value) or a custom Header implementation whose key() returns null, then serialising the record; copying header keys from an untrusted map without null checks.","commonSituations":"Dynamic header builders fed by user input or maps; mocking headers in tests; converters that copy headers verbatim from a source allowing null keys.","solutions":["Validate header keys before adding: reject null, or substitute an empty/default string.","Filter null-key entries out of the header map before record assembly.","If using RecordHeader, ensure the key argument is non-null at construction."],"exampleFix":"// before\nheaders.add(new RecordHeader(mapKey, value));\n// after\nif (mapKey == null) throw new IllegalArgumentException(\"header key required\");\nheaders.add(new RecordHeader(mapKey, value));","handlingStrategy":"validation","validationCode":"// Reject or drop records whose headers contain a null key before serializing\nimport org.apache.kafka.common.header.Header;\nimport org.apache.kafka.common.record.Record;\n\nHeader[] sanitized;\nif (headers == null) {\n    sanitized = Record.EMPTY_HEADERS;\n} else {\n    java.util.List<Header> kept = new java.util.ArrayList<>(headers.length);\n    for (Header h : headers) {\n        if (h != null && h.key() != null) kept.add(h);\n    }\n    sanitized = kept.toArray(new Header[0]);\n}\n// pass sanitized to DefaultRecord.writeTo / ProducerRecord","typeGuard":"import org.apache.kafka.common.header.Header;\n\nstatic boolean allHeaderKeysPresent(Header[] headers) {\n    if (headers == null) return false;\n    for (Header h : headers) {\n        if (h == null || h.key() == null) return false;\n    }\n    return true;\n}\n\n// usage: if (allHeaderKeysPresent(headers)) { DefaultRecord.writeTo(...); }","tryCatchPattern":"try {\n    DefaultRecord.writeTo(out, offsetDelta, tsDelta, key, value, headers);\n} catch (IllegalArgumentException e) {\n    // a header key was null; strip offending headers or fail the record\n}","preventionTips":["Header keys must be non-null strings; null is invalid at the format level.","Validate header keys at the point you accept them from callers/users rather than deep in serialization.","Consider using RecordHeader directly and asserting key != null in its constructor/wrapper.","A single null key invalidates the whole record write; fail fast on the first offender."],"tags":["record-format","serialization","headers"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}