{"id":"d505eacb19bee447","repo":"apache/kafka","slug":"invalid-value-null-for-configuration-key-deseriali","errorCode":null,"errorMessage":"Invalid value null for configuration key.deserializer: must be non-null.","messagePattern":"Invalid value null for configuration key\\.deserializer: must be non-null\\.","errorType":"exception","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerConfig.java","lineNumber":798,"sourceCode":"            String groupInstanceId = this.getString(GROUP_INSTANCE_ID_CONFIG);\n            if (groupInstanceId != null)\n                JoinGroupRequest.validateGroupInstanceId(groupInstanceId);\n\n            String groupInstanceIdPart = groupInstanceId != null ? groupInstanceId : CONSUMER_CLIENT_ID_SEQUENCE.getAndIncrement() + \"\";\n            String generatedClientId = String.format(\"consumer-%s-%s\", groupId, groupInstanceIdPart);\n            configs.put(CLIENT_ID_CONFIG, generatedClientId);\n        }\n    }\n\n    public static Map<String, Object> appendDeserializerToConfig(Map<String, Object> configs,\n                                                                 Deserializer<?> keyDeserializer,\n                                                                 Deserializer<?> valueDeserializer) {\n        // validate deserializer configuration, if the passed deserializer instance is null, the user must explicitly set a valid deserializer configuration value\n        Map<String, Object> newConfigs = new HashMap<>(configs);\n        if (keyDeserializer != null)\n            newConfigs.put(KEY_DESERIALIZER_CLASS_CONFIG, keyDeserializer.getClass());\n        else if (newConfigs.get(KEY_DESERIALIZER_CLASS_CONFIG) == null)\n            throw new ConfigException(KEY_DESERIALIZER_CLASS_CONFIG, null, \"must be non-null.\");\n        if (valueDeserializer != null)\n            newConfigs.put(VALUE_DESERIALIZER_CLASS_CONFIG, valueDeserializer.getClass());\n        else if (newConfigs.get(VALUE_DESERIALIZER_CLASS_CONFIG) == null)\n            throw new ConfigException(VALUE_DESERIALIZER_CLASS_CONFIG, null, \"must be non-null.\");\n        return newConfigs;\n    }\n\n    private void maybeOverrideEnableAutoCommit(Map<String, Object> configs) {\n        Optional<String> groupId = Optional.ofNullable(getString(CommonClientConfigs.GROUP_ID_CONFIG));\n        Map<String, Object> originals = originals();\n        boolean enableAutoCommit = originals.containsKey(ENABLE_AUTO_COMMIT_CONFIG) ? getBoolean(ENABLE_AUTO_COMMIT_CONFIG) : false;\n        if (groupId.isEmpty()) { // overwrite in case of default group id where the config is not explicitly provided\n            if (!originals.containsKey(ENABLE_AUTO_COMMIT_CONFIG)) {\n                configs.put(ENABLE_AUTO_COMMIT_CONFIG, false);\n            } else if (enableAutoCommit) {\n                throw new InvalidConfigurationException(ENABLE_AUTO_COMMIT_CONFIG + \" cannot be set to true when default group id (null) is used.\");\n            }\n        }","sourceCodeStart":780,"sourceCodeEnd":816,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerConfig.java#L780-L816","documentation":"Thrown by ConsumerConfig.appendDeserializerToConfig when neither a key Deserializer instance nor the key.deserializer configuration property is provided. Every KafkaConsumer must know how to turn byte[] keys into objects; the client refuses to construct without one. It is a ConfigException raised during KafkaConsumer initialization.","triggerScenarios":"new KafkaConsumer<>(props) (or KafkaConsumer(Map, Deserializer, Deserializer) with keyDeserializer=null) where props does not contain key.deserializer, or where key.deserializer is explicitly set to null.","commonSituations":"Forgetting to set key.deserializer when building a Properties/Map consumer; passing a non-null value Deserializer but a null key Deserializer to the typed constructor without also setting the config; mis-spelling the property name (e.g. key.deserializer.class); reading config from a file that silently dropped the key.","solutions":["Set props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName()); before constructing the consumer.","Or pass a non-null key Deserializer instance to the KafkaConsumer(Map, Deserializer, Deserializer) constructor.","Validate config keys at startup (log ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG) to catch typos like key.deserializer.class.","If keys are intentionally unused, still provide a ByteArrayDeserializer for the key."],"exampleFix":"// before\nProperties props = new Properties();\nprops.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, \"localhost:9092\");\nprops.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());\nnew KafkaConsumer<>(props); // throws: key.deserializer null\n\n// after\nprops.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());\nnew KafkaConsumer<>(props);","handlingStrategy":"validation","validationCode":"// Ensure key.deserializer is set before constructing the consumer:\nProperties props = new Properties();\nprops.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());\n// or pass a Deserializer instance to the KafkaConsumer constructor\nif (props.get(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG) == null && keyDeserializer == null) {\n    throw new ConfigException(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, null, \"must be non-null\");\n}","typeGuard":"static boolean hasKeyDeserializer(Map<String, Object> configs, Deserializer<?> instance) {\n    return instance != null || configs.get(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG) != null;\n}","tryCatchPattern":"try {\n    new KafkaConsumer<>(props);\n} catch (ConfigException e) {\n    if (e.getMessage().contains(\"key.deserializer\")) {\n        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());\n        new KafkaConsumer<>(props);\n    } else throw e;\n}","preventionTips":["Always set key.deserializer (either the config property or pass a Deserializer instance to the KafkaConsumer constructor).","Build a helper or config builder that injects default deserializers so a missing one is impossible.","Use the KafkaConsumer(Map, Deserializer<K>, Deserializer<V>) constructor when you already have instances - it also covers the value side."],"tags":["consumer","configuration","deserializer","startup","java"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}