apache/kafka · error · ConfigException

providerClassName is not allowed. Update System property 'AU

Error message

providerClassName is not allowed. Update System property 'AUTOMATIC_CONFIG_PROVIDERS_PROPERTY' to allow providerClassName

What it means

ConfigException thrown by instantiateConfigProviders when an *automatic* (implicit) config provider's class name is not on the allowlist. Kafka resolves ${provider:[path:]key} variables in config values; when a variable references a provider that was not explicitly declared via the 'config.providers' setting (so it is being auto-instantiated), the class name must pass a classNameFilter derived from the system property org.apache.kafka.automatic.config.providers. If unset, all classes are allowed (filter is 'always true'); if set, only the comma-separated listed class names pass. The exception names the rejected class and tells you how to allow it.

Source

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

            Map<String, ?> providerConfigProperties,
            Predicate<String> classNameFilter
    ) {
        final String configProviders = indirectConfigs.get(CONFIG_PROVIDERS_CONFIG);

        if (configProviders == null || configProviders.isEmpty()) {
            return Map.of();
        }

        Map<String, String> providerMap = new HashMap<>();

        for (String provider : configProviders.split(",")) {
            String providerClass = providerClassProperty(provider);
            if (indirectConfigs.containsKey(providerClass)) {
                String providerClassName = indirectConfigs.get(providerClass);
                if (classNameFilter.test(providerClassName)) {
                    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");
            }
        }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Add the rejected class name (shown verbatim in the message) to the JVM system property: -Dorg.apache.kafka.automatic.config.providers=org.apache.kafka.common.config.provider.FileConfigProvider (comma-separated for multiple).
2. Prefer declaring the provider explicitly via 'config.providers=file' and 'config.providers.file.class=org.apache.kafka.common.config.provider.FileConfigProvider' instead of relying on automatic resolution; explicitly-declared providers bypass the allowlist.
3. Verify the FQCN matches exactly (mind shading/relocation that renames packages).
4. If running in a container/K8s, ensure the -D flag is actually applied to the JVM running Kafka/Connect/Streams (not just the shell).

Example fix

// before: JVM started with a restrictive allowlist that omits FileConfigProvider
//   -Dorg.apache.kafka.automatic.config.providers=org.apache.kafka.common.config.provider.DirectoryConfigProvider
// and a config value uses ${file:/etc/app/app.properties:db.url}

// after: add FileConfigProvider to the allowlist
//   -Dorg.apache.kafka.automatic.config.providers=org.apache.kafka.common.config.provider.DirectoryConfigProvider,org.apache.kafka.common.config.provider.FileConfigProvider

// Explicitly allow only the providers you trust via the system property BEFORE the
// AbstractConfig is constructed.
String providers = "file,classpath,env"; // your chosen allowlist of FQCNs
System.setProperty(
    org.apache.kafka.common.config.AbstractConfig.AUTOMATIC_CONFIG_PROVIDERS_PROPERTY,
    providers);
// Then construct your config; only listed FQCNs will be accepted by the framework.
// Do NOT put arbitrary user-supplied class names in `config.providers`.

try {
    AbstractConfig cfg = new MyConfigDef().parse(props);
} catch (org.apache.kafka.common.config.ConfigException ce) {
    if (ce.getMessage().endsWith("Update System property '" +
            org.apache.kafka.common.config.AbstractConfig.AUTOMATIC_CONFIG_PROVIDERS_PROPERTY
            + "' to allow " + props.get("config.providers.file.class"))) {
        // either allowlist it explicitly or remove the provider from the config
        log.error("ConfigProvider not allowlisted; set -Dorg.apache.kafka.automatic.config.providers=<fqcn>");
    } else {
        throw ce;
    }
}

When it happens

Trigger: A config value contains a variable like ${file:/etc/app/db.properties:password} or ${vault:secret/path:key}; 'file'/'vault' were not declared under 'config.providers', so they are treated as automatic providers. The JVM was started with -Dorg.apache.kafka.automatic.config.providers=some,classes (non-empty), and the resolved provider class (e.g. org.apache.kafka.common.config.provider.FileConfigProvider) is not in that list, so classNameFilter.test(...) returns false and the exception fires.

Common situations: See trigger scenarios.

Related errors

• lz4 doesn't support given compression level: level
• zstd doesn't support given compression level: level
• Unknown configuration '%s'
• Non-string value found in original settings for key entry.ge
• Class klass cannot be found

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