{"record":{"id":"cff3cef7b9df1504","repo":"apache/kafka","slug":"klass-classnotfoundexception-exception-occurred","errorCode":null,"errorMessage":"{klass} ClassNotFoundException exception occurred","messagePattern":"(.+?) ClassNotFoundException exception occurred","errorType":"validation","errorClass":"KafkaException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerPartitionAssignor.java","lineNumber":429,"sourceCode":"        }\n    }\n\n    /**\n     * Get a list of configured instances of {@link org.apache.kafka.clients.consumer.ConsumerPartitionAssignor}\n     * based on the class names/types specified by {@link org.apache.kafka.clients.consumer.ConsumerConfig#PARTITION_ASSIGNMENT_STRATEGY_CONFIG}\n     */\n    static List<ConsumerPartitionAssignor> getAssignorInstances(List<String> assignorClasses, Map<String, Object> configs) {\n        List<ConsumerPartitionAssignor> assignors = new ArrayList<>();\n        // a map to store assignor name -> assignor class name\n        Map<String, String> assignorNameMap = new HashMap<>();\n\n        for (Object klass : assignorClasses) {\n            // first try to get the class if passed in as a string\n            if (klass instanceof String) {\n                try {\n                    klass = Utils.loadClass((String) klass, Object.class);\n                } catch (ClassNotFoundException classNotFound) {\n                    throw new KafkaException(klass + \" ClassNotFoundException exception occurred\", classNotFound);\n                }\n            }\n\n            if (klass instanceof Class<?>) {\n                Object assignor = Utils.newInstance((Class<?>) klass);\n                if (assignor instanceof Configurable)\n                    ((Configurable) assignor).configure(configs);\n\n                if (assignor instanceof ConsumerPartitionAssignor) {\n                    String assignorName = ((ConsumerPartitionAssignor) assignor).name();\n                    if (assignorNameMap.containsKey(assignorName)) {\n                        throw new KafkaException(\"The assignor name: '\" + assignorName + \"' is used in more than one assignor: \" +\n                            assignorNameMap.get(assignorName) + \", \" + assignor.getClass().getName());\n                    }\n                    assignorNameMap.put(assignorName, assignor.getClass().getName());\n                    assignors.add((ConsumerPartitionAssignor) assignor);\n                } else {\n                    throw new KafkaException(klass + \" is not an instance of \" + ConsumerPartitionAssignor.class.getName());","sourceCodeStart":411,"sourceCodeEnd":447,"githubUrl":"https://github.com/apache/kafka/blob/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerPartitionAssignor.java#L411-L447","documentation":"Thrown by ConsumerPartitionAssignor.getAssignorInstances when a class name listed in partition.assignment.strategy cannot be loaded by Utils.loadClass, raising ClassNotFoundException which is then wrapped in a KafkaException. The consumer cannot start without its assignor(s); the listed class must be on the classpath and accessible.","triggerScenarios":"Setting partition.assignment.strategy to a fully-qualified class name that is not on the consumer's classpath; misspelling the class name; referencing a class in a jar that wasn't packaged with the application.","commonSituations":"Custom assignor not packaged in the deployed jar/shaded uber-jar; copy-paste of a class name from another project; typo in the FQN; jar present at compile time but excluded at runtime (scope/proguard).","solutions":["Verify the class name is correct and the jar is on the runtime classpath (use the built-in org.apache.kafka.clients.consumer.CooperativeStickyAssignor if unsure).","If using a custom assignor, package it in the application jar (or an ubershaded jar) so it ships with the consumer.","For framework users (Spring etc.) make sure the dependency is not marked provided/optional."],"exampleFix":"// before\nprops.put(\"partition.assignment.strategy\",\n    \"com.example.MyCustomAssignor\"); // not on classpath\nnew KafkaConsumer<>(props);\n\n// after\nprops.put(\"partition.assignment.strategy\",\n    CooperativeStickyAssignor.class.getName());\nnew KafkaConsumer<>(props);","handlingStrategy":"try-catch","validationCode":"for (String name : assignorClassNames) {\n    try {\n        Class.forName(name);\n    } catch (ClassNotFoundException e) {\n        throw new ConfigException(\"partition.assignment.strategy class not on classpath: \" + name);\n    }\n}","typeGuard":"static boolean isAssignorLoadable(String className) {\n    try { Class.forName(className); return true; }\n    catch (ClassNotFoundException e) { return false; }\n}","tryCatchPattern":"try {\n    consumer = new KafkaConsumer<>(props);\n} catch (KafkaException e) {\n    if (e.getCause() instanceof ClassNotFoundException) {\n        throw new ConfigException(\"Assignor class not on classpath: \" + e.getCause().getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Package custom assignors in the application uber-jar; do not mark the dependency 'provided'.","Use built-in assignors (CooperativeStickyAssignor, StableAssignor) unless a custom one is required.","Add a startup check that Class.forName succeeds for each configured assignor."],"tags":["consumer","config","classpath","partition-assignor","illegal-state"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}