apache/kafka · error · ConfigException

Class value could not be found.

Error message

Class value could not be found.

What it means

Catch block in ConfigDef.parseType wrapping a ClassNotFoundException raised by Utils.loadClass during the Type.CLASS branch. The library tried to resolve the supplied fully-qualified class name onto the classpath and the JVM could not find it. The thrown ConfigException echoes the offending value so the developer can see which class name failed to load.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java:791

                            return List.of();
                        else
                            return Arrays.asList(COMMA_WITH_WHITESPACE.split(trimmed, -1));
                    else
                        throw new ConfigException(name, value, "Expected a comma separated list.");
                case CLASS:
                    if (value instanceof Class)
                        return value;
                    else if (value instanceof String) {
                        return Utils.loadClass(trimmed, Object.class);
                    } else
                        throw new ConfigException(name, value, "Expected a Class instance or class name.");
                default:
                    throw new IllegalStateException("Unknown type.");
            }
        } catch (NumberFormatException e) {
            throw new ConfigException(name, value, "Not a number of type " + type);
        } catch (ClassNotFoundException e) {
            throw new ConfigException(name, value, "Class " + value + " could not be found.");
        }
    }

    /**
     * Convert the provided object into a string based on its type.
     * <p>
     * This method uses Java's {@link #toString()} for {@link Type#BOOLEAN}, {@link Type#SHORT}, {@link Type#INT},
     * {@link Type#LONG}, {@link Type#DOUBLE}, {@link Type#STRING} and {@link Type#PASSWORD} objects.
     * For {@link Type#LIST} objects, Java's {@link #toString()} is used for each entry and entries are concatenated
     * separated by commas. For {@link Type#CLASS} objects, {@link Class#getName()} is used.
     * @param parsedValue The object to convert into a string
     * @param type The type of the object
     * @return The string representation of the provided object and type
     */
    public static String convertToString(Object parsedValue, Type type) {
        if (parsedValue == null) {
            return null;
        }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Verify the class name spelling and package path against the actual jar (use jar tf / javap -classpath to confirm).
2. Ensure the jar containing the class is on the runtime classpath of the producer/consumer/broker/connect worker (e.g. Kafka libs dir, plugin.path for Connect, uber-jar for Streams).
3. If using a shade/relocate plugin, use the relocated package name in the config.
4. Make sure the class is public and (for serializers/deserializers/converters) has a public no-arg constructor.
5. Re-package and redeploy: a stale deployment without the new jar is the most common cause after an upgrade.

Example fix

// before
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG,
         "com.acme.InvalidSerializer"); // typo -> ClassNotFoundException

// after
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG,
         "com.acme.InventorySerializer");

if (value instanceof String) {
    String cls = ((String) value).trim();
    try {
        Class.forName(cls, false, Thread.currentThread().getContextClassLoader());
    } catch (ClassNotFoundException cnfe) {
        throw new IllegalArgumentException("Class '" + cls + "' is not on the classpath", cnfe);
    }
}

public static boolean isClassLoadable(String className) {
    try {
        Class.forName(className, false, Thread.currentThread().getContextClassLoader());
        return true;
    } catch (Throwable t) {
        return false;
    }
}

try {
    configDef.parse(configs);
} catch (ConfigException e) {
    if (e.getMessage().contains("could not be found")) {
        // ensure the plugin jar is on the classpath / plugin.path, then retry
    } else throw e;
}

When it happens

Trigger: Setting a CLASS-typed config (key.serializer, value.deserializer, partitioner.class, sasl.client.callback.handler.class, security.providers, metric.reporters, client.dns.lookup custom impl, etc.) to an FQCN that is not present on the runtime classpath — typo, missing jar, wrong package, or class not public.

Common situations: Custom serializer/deserializer/partitioner in a separate module not packaged into the fat jar; Kafka Connect worker missing a converter plugin jar; shaded uber-jar that rewrote package names; typo in the FQCN; connector/plugin JAR installed in the wrong lib directory; class present only in test scope and not in the runtime artifact.

Related errors

• Expected a Class instance or class name.
• Invalid url in bootstrap.servers: {url}
• Could not load config provider class or one of its dependenc
• Expected value to be a 64-bit integer (long), but it was a v
• Expected value to be a double, but it was a value.getClass()

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