apache/kafka · error · KafkaException

Class klass cannot be found

Error message

Class klass cannot be found

What it means

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.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/config/AbstractConfig.java:408

     * Info level log for any unused configurations
     */
    public void logUnused() {
        Set<String> unusedKeys = unused();
        if (!unusedKeys.isEmpty()) {
            log.info("These configurations '{}' were supplied but are not used yet.", unusedKeys);
        }
    }

    private <T> T getConfiguredInstance(Object klass, Class<T> t, Map<String, Object> configPairs) {
        if (klass == null)
            return null;
        Object o;

        if (klass instanceof String) {
            try {
                o = Utils.newInstance((String) klass, t);
            } catch (ClassNotFoundException e) {
                throw new KafkaException("Class " + klass + " cannot be found", e);
            }
        } else if (klass instanceof Class<?>) {
            o = Utils.newInstance((Class<?>) klass);
        } else
            throw new KafkaException("Unexpected element of type " + klass.getClass().getName() + ", expected String or Class");
        try {
            if (!t.isInstance(o))
                throw new KafkaException(klass + " is not an instance of " + t.getName());
            if (o instanceof Configurable)
                ((Configurable) o).configure(configPairs);
        } catch (Exception e) {
            maybeClose(o, "AutoCloseable object constructed and configured during failed call to getConfiguredInstance");
            throw e;
        }
        return t.cast(o);
    }

    /**

View on GitHub (pinned to c31c9215e1)

Solutions

1. 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).
2. Check the fully-qualified class name spelling and package (watch for relocations from shading, e.g. com.example.X vs a relocated package).
3. Confirm the library version exposes that class (the API may have been renamed/removed in a newer version).
4. For Kafka Connect, ensure plugin isolation includes the connector/transform/converter and its transitive deps; check worker logs for earlier classloading errors.

Example fix

// before: wrong package / typo in the configured class name
props.put("partitioner.class", "org.apache.kafka.client.producer.internals.DefaultPartitioner");

// after: correct FQCN
props.put("partitioner.class", "org.apache.kafka.clients.producer.internals.DefaultPartitioner");

// Resolve the class yourself before letting Kafka instantiate it, so the error is actionable.
String className = (String) config.getClassName(key); // or wherever it came from
Class<?> resolved;
try {
    resolved = Class.forName(className, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException cnfe) {
    throw new IllegalArgumentException("Class '" + className + "' is not on the classpath; add the dependency or fix the config", cnfe);
}
// then: config.getConfiguredInstance(key, T.class) will succeed

try {
    T plugin = config.getConfiguredInstance(key, T.class);
} catch (org.apache.kafka.common.KafkaException ke) {
    if (ke.getCause() instanceof ClassNotFoundException) {
        // message: "Class X cannot be found"
        log.error("Plugin class '{}' missing from classpath; deploy the jar / shade the dependency",
                config.get(key));
    } else {
        throw ke;
    }
}

When it happens

Trigger: 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'.

Common situations: See trigger scenarios.

Related errors

• klass is not an instance of t.getName()
• {klass} ClassNotFoundException exception occurred
• lz4 doesn't support given compression level: level
• zstd doesn't support given compression level: level
• Unknown configuration '%s'

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/3112aa77cccd6384.json. Report an issue: GitHub.