{"id":"3112aa77cccd6384","repo":"apache/kafka","slug":"class-klass-cannot-be-found","errorCode":null,"errorMessage":"Class klass cannot be found","messagePattern":"Class klass cannot be found","errorType":"exception","errorClass":"KafkaException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/config/AbstractConfig.java","lineNumber":408,"sourceCode":"     * Info level log for any unused configurations\n     */\n    public void logUnused() {\n        Set<String> unusedKeys = unused();\n        if (!unusedKeys.isEmpty()) {\n            log.info(\"These configurations '{}' were supplied but are not used yet.\", unusedKeys);\n        }\n    }\n\n    private <T> T getConfiguredInstance(Object klass, Class<T> t, Map<String, Object> configPairs) {\n        if (klass == null)\n            return null;\n        Object o;\n\n        if (klass instanceof String) {\n            try {\n                o = Utils.newInstance((String) klass, t);\n            } catch (ClassNotFoundException e) {\n                throw new KafkaException(\"Class \" + klass + \" cannot be found\", e);\n            }\n        } else if (klass instanceof Class<?>) {\n            o = Utils.newInstance((Class<?>) klass);\n        } else\n            throw new KafkaException(\"Unexpected element of type \" + klass.getClass().getName() + \", expected String or Class\");\n        try {\n            if (!t.isInstance(o))\n                throw new KafkaException(klass + \" is not an instance of \" + t.getName());\n            if (o instanceof Configurable)\n                ((Configurable) o).configure(configPairs);\n        } catch (Exception e) {\n            maybeClose(o, \"AutoCloseable object constructed and configured during failed call to getConfiguredInstance\");\n            throw e;\n        }\n        return t.cast(o);\n    }\n\n    /**","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/config/AbstractConfig.java#L390-L426","documentation":"KafkaException thrown by the private getConfiguredInstance(Object klass, Class<T> t, ...) when the supplied class name cannot be resolved by the classloader (Utils.newInstance(String, t) raised ClassNotFoundException). This is the mechanism behind getConfiguredInstance / getConfiguredInstances used to instantiate partitioners, serializers, deserializers, interceptors, metrics reporters, Connect converters/transforms, config providers, etc. The message names the missing class so it is clear which configured component failed to load.","triggerScenarios":"A config key whose value is a class name (e.g. partitioner.class, key.serializer, interceptor.classes, value.converter, config.providers.X.class, metric.reporters) points at a class not on the classpath. getConfiguredInstance triggers Utils.newInstance(className, t), which throws ClassNotFoundException, wrapped here as KafkaException 'Class X cannot be found'.","commonSituations":"See trigger scenarios.","solutions":["Verify the JAR containing the class is on the classpath (for Connect, place it under the plugin path directory and restart; for clients, add the dependency).","Check the fully-qualified class name spelling and package (watch for relocations from shading, e.g. com.example.X vs a relocated package).","Confirm the library version exposes that class (the API may have been renamed/removed in a newer version).","For Kafka Connect, ensure plugin isolation includes the connector/transform/converter and its transitive deps; check worker logs for earlier classloading errors."],"exampleFix":"// before: wrong package / typo in the configured class name\nprops.put(\"partitioner.class\", \"org.apache.kafka.client.producer.internals.DefaultPartitioner\");\n\n// after: correct FQCN\nprops.put(\"partitioner.class\", \"org.apache.kafka.clients.producer.internals.DefaultPartitioner\");","handlingStrategy":"try-catch","validationCode":"// Resolve the class yourself before letting Kafka instantiate it, so the error is actionable.\nString className = (String) config.getClassName(key); // or wherever it came from\nClass<?> resolved;\ntry {\n    resolved = Class.forName(className, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException cnfe) {\n    throw new IllegalArgumentException(\"Class '\" + className + \"' is not on the classpath; add the dependency or fix the config\", cnfe);\n}\n// then: config.getConfiguredInstance(key, T.class) will succeed","typeGuard":null,"tryCatchPattern":"try {\n    T plugin = config.getConfiguredInstance(key, T.class);\n} catch (org.apache.kafka.common.KafkaException ke) {\n    if (ke.getCause() instanceof ClassNotFoundException) {\n        // message: \"Class X cannot be found\"\n        log.error(\"Plugin class '{}' missing from classpath; deploy the jar / shade the dependency\",\n                config.get(key));\n    } else {\n        throw ke;\n    }\n}","preventionTips":["Almost always a missing jar or a fat-jar/shaded-jar classloader issue.","Use Kafka's ServiceLoader / plugin.path mechanism for custom serializers/partitioners so classes are loadable.","Add an integration test that calls getConfiguredInstance for every pluggable class in your config.","Verify the FQCN spelling in config — a rename can silently move the class out of reach."],"tags":["configuration","kafka-client","classloading","connect","plugins"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}