{"id":"f5e955d0911cec06","repo":"apache/kafka","slug":"could-not-load-config-provider-class-or-one-of-its","errorCode":null,"errorMessage":"Could not load config provider class or one of its dependencies","messagePattern":"Could not load config provider class or one of its dependencies","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/config/AbstractConfig.java","lineNumber":639,"sourceCode":"                    providerMap.put(provider, providerClassName);\n                } else {\n                    throw new ConfigException(providerClassName + \" is not allowed. Update System property '\"\n                            + AUTOMATIC_CONFIG_PROVIDERS_PROPERTY + \"' to allow \" + providerClassName);\n                }\n            }\n        }\n        // Instantiate Config Providers\n        Map<String, ConfigProvider> configProviderInstances = new HashMap<>();\n        for (Map.Entry<String, String> entry : providerMap.entrySet()) {\n            try {\n                String prefix = CONFIG_PROVIDERS_CONFIG + \".\" + entry.getKey() + CONFIG_PROVIDERS_PARAM;\n                Map<String, ?> configProperties = configProviderProperties(prefix, providerConfigProperties);\n                ConfigProvider provider = Utils.newInstance(entry.getValue(), ConfigProvider.class);\n                provider.configure(configProperties);\n                configProviderInstances.put(entry.getKey(), provider);\n            } catch (ClassNotFoundException e) {\n                log.error(\"Could not load config provider class {}\", entry.getValue(), e);\n                throw new ConfigException(providerClassProperty(entry.getKey()), entry.getValue(), \"Could not load config provider class or one of its dependencies\");\n            }\n        }\n\n        return configProviderInstances;\n    }\n\n    private static String providerClassProperty(String providerName) {\n        return String.format(\"%s.%s.class\", CONFIG_PROVIDERS_CONFIG, providerName);\n    }\n\n    @Override\n    public boolean equals(Object o) {\n        if (this == o) return true;\n        if (o == null || getClass() != o.getClass()) return false;\n\n        AbstractConfig that = (AbstractConfig) o;\n\n        return originals.equals(that.originals);","sourceCodeStart":621,"sourceCodeEnd":657,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/config/AbstractConfig.java#L621-L657","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconfig.providers=file\nconfig.providers.file.class=org.apache.kafka.common.config.provider.Fileprovider  // typo, class not found\n\n// after\nconfig.providers=file\nconfig.providers.file.class=org.apache.kafka.common.config.provider.FileConfigProvider","handlingStrategy":"try-catch","validationCode":"// Verify every declared config provider class is loadable BEFORE constructing the client.\nString providers = props.getProperty(\"config.providers\", \"\");\nfor (String name : providers.split(\",\")) {\n    if (name.trim().isEmpty()) continue;\n    String cls = props.getProperty(\"config.providers.\" + name.trim() + \".class\");\n    if (cls == null) {\n        throw new IllegalArgumentException(\"Missing 'config.providers.\" + name.trim() + \".class' property\");\n    }\n    try {\n        Class.forName(cls.trim(), false, Thread.currentThread().getContextClassLoader());\n    } catch (ClassNotFoundException cnfe) {\n        throw new IllegalStateException(\"Config provider '\" + cls + \"' is not on the classpath. Add the implementing jar/dependency.\", cnfe);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    this.client = new KafkaProducer<>(props); // or KafkaConsumer / Admin / Connect worker\n} catch (ConfigException e) {\n    if (e.getMessage().contains(\"Could not load config provider class\")) {\n        throw new IllegalStateException(\n            \"A declared config.providers.<name>.class could not be loaded. Check the class name for typos \" +\n            \"and ensure its jar (and transitive deps) are on the runtime classpath: \" + e.getMessage(), e);\n    }\n    throw e; // re-throw unrelated config errors unchanged\n}","preventionTips":["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."],"tags":["config","config-provider","classpath","connect","kafka-client"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}