apache/kafka · error · ConfigException

Could not load config provider class or one of its dependenc

Error message

Could not load config provider class or one of its dependencies

What it means

Thrown by AbstractConfig.instantiateConfigProviders when Utils.newInstance(...) raises ClassNotFoundException while loading a class declared via the config.providers.<name>.class property. Kafka uses ConfigProvider implementations (e.g. file, env, directory) to perform external variable substitution like ${file:/path:key}. The FQCN cannot be located on the classpath, so provider instantiation is aborted and a ConfigException is wrapped around the underlying CNFE.

Source

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

                    providerMap.put(provider, providerClassName);
                } else {
                    throw new ConfigException(providerClassName + " is not allowed. Update System property '"
                            + AUTOMATIC_CONFIG_PROVIDERS_PROPERTY + "' to allow " + providerClassName);
                }
            }
        }
        // Instantiate Config Providers
        Map<String, ConfigProvider> configProviderInstances = new HashMap<>();
        for (Map.Entry<String, String> entry : providerMap.entrySet()) {
            try {
                String prefix = CONFIG_PROVIDERS_CONFIG + "." + entry.getKey() + CONFIG_PROVIDERS_PARAM;
                Map<String, ?> configProperties = configProviderProperties(prefix, providerConfigProperties);
                ConfigProvider provider = Utils.newInstance(entry.getValue(), ConfigProvider.class);
                provider.configure(configProperties);
                configProviderInstances.put(entry.getKey(), provider);
            } catch (ClassNotFoundException e) {
                log.error("Could not load config provider class {}", entry.getValue(), e);
                throw new ConfigException(providerClassProperty(entry.getKey()), entry.getValue(), "Could not load config provider class or one of its dependencies");
            }
        }

        return configProviderInstances;
    }

    private static String providerClassProperty(String providerName) {
        return String.format("%s.%s.class", CONFIG_PROVIDERS_CONFIG, providerName);
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;

        AbstractConfig that = (AbstractConfig) o;

        return originals.equals(that.originals);

View on GitHub (pinned to c31c9215e1)

Solutions

Verify the FQCN in config.providers.<name>.class is spelled correctly and matches the package layout of your Kafka version (built-ins: org.apache.kafka.common.config.provider.FileConfigProvider, .DirectoryConfigProvider, .EnvConfigProvider).
Ensure the JAR containing the provider (and any transitive deps it needs) is on the runtime classpath; for the built-in providers this is kafka-clients and the connect/runtime module, for a custom provider ship its JAR plus its declared dependencies.
Inspect the logged ClassNotFoundException at the preceding log.error line (AbstractConfig.java:638) to see exactly which class is missing, then add that specific artifact.
If using a shaded/fat JAR or GraalVM native image, add the provider class and its dependencies to the inclusion list so they are not stripped.
If the provider is no longer needed, remove the config.providers entry and the corresponding config.providers.<name>.class line entirely.

Example fix

// before
config.providers=file
config.providers.file.class=org.apache.kafka.common.config.provider.Fileprovider  // typo, class not found

// after
config.providers=file
config.providers.file.class=org.apache.kafka.common.config.provider.FileConfigProvider

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify every declared config provider class is loadable BEFORE constructing the client.
String providers = props.getProperty("config.providers", "");
for (String name : providers.split(",")) {
    if (name.trim().isEmpty()) continue;
    String cls = props.getProperty("config.providers." + name.trim() + ".class");
    if (cls == null) {
        throw new IllegalArgumentException("Missing 'config.providers." + name.trim() + ".class' property");
    }
    try {
        Class.forName(cls.trim(), false, Thread.currentThread().getContextClassLoader());
    } catch (ClassNotFoundException cnfe) {
        throw new IllegalStateException("Config provider '" + cls + "' is not on the classpath. Add the implementing jar/dependency.", cnfe);
    }
}

Try / catch

try {
    this.client = new KafkaProducer<>(props); // or KafkaConsumer / Admin / Connect worker
} catch (ConfigException e) {
    if (e.getMessage().contains("Could not load config provider class")) {
        throw new IllegalStateException(
            "A declared config.providers.<name>.class could not be loaded. Check the class name for typos " +
            "and ensure its jar (and transitive deps) are on the runtime classpath: " + e.getMessage(), e);
    }
    throw e; // re-throw unrelated config errors unchanged
}

Prevention

Add the implementing jar for any non-built-in config provider to the runtime classpath (built-ins are 'file' and 'classpath').
Spell the fully-qualified class name exactly; classloading is not typo-tolerant.
Resolve variable references like ${file:/...} only after confirming the file/env provider dependency is present.
Keep provider dependencies declared in build.gradle/pom.xml, not loaded dynamically at runtime.

When it happens

Trigger: Setting config.providers=file (or env, directory, or a custom provider) in producer/consumer/connect/worker properties, then having config.providers.<name>.class point at an FQCN that is absent from the classpath; also triggered by a typo in the class name or a missing transitive dependency of the provider class. The provider class is looked up via Utils.newInstance(entry.getValue(), ConfigProvider.class) inside the providerMap loop in AbstractConfig.java:634.

Common situations: Running a Kafka Connect worker or client in a stripped classpath (shaded JAR, native image, OSGi bundle) where the provider JAR was not packaged; using the built-in org.apache.kafka.common.config.provider.FileConfigProvider / DirectoryConfigProvider / EnvConfigProvider on a distribution that omits them; upgrading Kafka versions where the provider package moved; a custom ConfigProvider whose dependency JAR is missing; referencing config.providers=file when the kafka-clients artifact alone is on the path without the connect runtime that ships these providers.

Related errors

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