{"id":"dfcdb46ba9d20427","repo":"apache/kafka","slug":"invalid-value-null-for-configuration-key-serialize","errorCode":null,"errorMessage":"Invalid value null for configuration key.serializer: must be non-null.","messagePattern":"Invalid value null for configuration key\\.serializer: must be non-null\\.","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/producer/ProducerConfig.java","lineNumber":721,"sourceCode":"    }\n\n    private static String parseAcks(String acksString) {\n        try {\n            return acksString.trim().equalsIgnoreCase(\"all\") ? \"-1\" : Short.parseShort(acksString.trim()) + \"\";\n        } catch (NumberFormatException e) {\n            throw new ConfigException(\"Invalid configuration value for 'acks': \" + acksString);\n        }\n    }\n\n    static Map<String, Object> appendSerializerToConfig(Map<String, Object> configs,\n            Serializer<?> keySerializer,\n            Serializer<?> valueSerializer) {\n        // validate serializer configuration, if the passed serializer instance is null, the user must explicitly set a valid serializer configuration value\n        Map<String, Object> newConfigs = new HashMap<>(configs);\n        if (keySerializer != null)\n            newConfigs.put(KEY_SERIALIZER_CLASS_CONFIG, keySerializer.getClass());\n        else if (newConfigs.get(KEY_SERIALIZER_CLASS_CONFIG) == null)\n            throw new ConfigException(KEY_SERIALIZER_CLASS_CONFIG, null, \"must be non-null.\");\n        if (valueSerializer != null)\n            newConfigs.put(VALUE_SERIALIZER_CLASS_CONFIG, valueSerializer.getClass());\n        else if (newConfigs.get(VALUE_SERIALIZER_CLASS_CONFIG) == null)\n            throw new ConfigException(VALUE_SERIALIZER_CLASS_CONFIG, null, \"must be non-null.\");\n        return newConfigs;\n    }\n\n    /**\n     * Constructs a new ProducerConfig with the given properties.\n     *\n     * @param props The producer configuration properties\n     */\n    public ProducerConfig(Properties props) {\n        super(CONFIG, props);\n    }\n\n    /**\n     * Constructs a new ProducerConfig with the given configuration map.","sourceCodeStart":703,"sourceCodeEnd":739,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/producer/ProducerConfig.java#L703-L739","documentation":"Thrown by ProducerConfig.appendSerializerToConfig when no key serializer can be determined. The producer needs a Serializer for every record key; if neither a keySerializer instance was passed to the KafkaProducer constructor nor a `key.serializer` class is present in the config map, this ConfigException is raised naming the KEY_SERIALIZER_CLASS_CONFIG with value null.","triggerScenarios":"Constructing `new KafkaProducer<>(props)` where props has no `key.serializer` entry AND no key Serializer instance is passed; or constructing `new KafkaProducer<>(props, null, valueSerializer)`.","commonSituations":"First-time producer setup where the developer forgot the serializer property; using a properties file that failed to load; or programmatically building a Properties object and forgetting to call props.put(\"key.serializer\", ...). Common with custom key types like UUID or Avro where the serializer class name must be spelled fully.","solutions":["Set `key.serializer` to the fully-qualified name of an appropriate Serializer, e.g. org.apache.kafka.common.serialization.StringSerializer.","Alternatively pass a Serializer<?> instance as the second argument to the KafkaProducer constructor.","For Avro/Protobuf, use the corresponding Confluent or framework serializer class."],"exampleFix":"// before\nProperties props = new Properties();\nprops.put(\"bootstrap.servers\", \"localhost:9092\");\nnew KafkaProducer<String,String>(props);\n\n// after\nProperties props = new Properties();\nprops.put(\"bootstrap.servers\", \"localhost:9092\");\nprops.put(\"key.serializer\", \"org.apache.kafka.common.serialization.StringSerializer\");\nprops.put(\"value.serializer\", \"org.apache.kafka.common.serialization.StringSerializer\");\nnew KafkaProducer<String,String>(props);","handlingStrategy":"type-guard","validationCode":"// Ensure a key serializer is present BEFORE constructing KafkaProducer.\nstatic void ensureKeySerializer(Map<String, Object> cfg, Serializer<?> keySer) {\n    if (keySer != null) return;\n    Object cls = cfg.get(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG);\n    if (cls == null || (cls instanceof String && ((String) cls).isEmpty()))\n        throw new IllegalArgumentException(\"key.serializer must be set (class or instance)\");\n}\n// Caller:\nensureKeySerializer(cfg, keySerializer);","typeGuard":"// Narrow to a non-null serializer guarantee.\nstatic boolean hasKeySerializer(Map<String, Object> cfg, Serializer<?> instance) {\n    if (instance != null) return true;\n    Object v = cfg.get(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG);\n    return v instanceof Class || (v instanceof String && !((String) v).isEmpty());\n}\n// Use: assert hasKeySerializer(cfg, keySerializer);","tryCatchPattern":"try {\n    producer = new KafkaProducer<>(cfg, keySerializer, valueSerializer);\n} catch (ConfigException e) {\n    if (e.getMessage().contains(\"key.serializer\")) {\n        // Pick a serializer matching your key type, e.g. StringSerializer.\n        keySerializer = new org.apache.kafka.common.serialization.StringSerializer();\n        producer = new KafkaProducer<>(cfg, keySerializer, valueSerializer);\n    } else throw e;\n}","preventionTips":["Always pass an explicit Serializer<KeyType> instance, or set key.serializer.class, keyed to your actual key type.","Match serializer to key type at compile time with generics: new KafkaProducer<K,V>(cfg, Serdes, Serdes).","Beware copy-pasting a value-only config template — key.serializer is the most commonly omitted sibling."],"tags":["kafka","producer","configuration","serialization"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}