{"record":{"id":"b6c7cdeac382b70e","repo":"brettwooldridge/HikariCP","slug":"failed-to-instantiate-class-credentialsproviderc","errorCode":null,"errorMessage":"Failed to instantiate class ${credentialsProviderClassName}","messagePattern":"Failed to instantiate class (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":896,"sourceCode":"      return credentialsProviderClassName;\n   }\n\n   /**\n    * Set the class name of the {@link HikariCredentialsProvider} that will be used to get credentials at runtime. Use this method\n    * or provide a {@link HikariCredentialsProvider} instance via the {@link #setCredentialsProvider(HikariCredentialsProvider)} method.\n    *\n    * @param credentialsProviderClassName the class name of the credentials provider\n    * @see HikariCredentialsProvider\n    */\n   public void setCredentialsProviderClassName(String credentialsProviderClassName) {\n      checkIfSealed();\n\n      try {\n         this.credentialsProvider = createInstance(credentialsProviderClassName, HikariCredentialsProvider.class);\n         this.exceptionOverrideClassName = credentialsProviderClassName;\n      }\n      catch (Exception e) {\n         throw new RuntimeException(\"Failed to instantiate class \" + credentialsProviderClassName, e);\n      }\n   }\n\n   /**\n    * Get the {@link HikariCredentialsProvider} instance created by {@link #setCredentialsProviderClassName(String)} or specified by\n    * {@link #setCredentialsProvider(HikariCredentialsProvider)}.\n    *\n    * @return the HikariCredentialsProvider instance, or null\n    * @see HikariCredentialsProvider\n    */\n   public HikariCredentialsProvider getCredentialsProvider() {\n      return credentialsProvider;\n   }\n\n   /**\n    * Set a user supplied {@link HikariCredentialsProvider} instance. If this method is used, then the {@link #setCredentialsProviderClassName(String)}\n    * method should not be used. The {@link HikariCredentialsProvider} instance will be used to get credentials at runtime.\n    *","sourceCodeStart":878,"sourceCodeEnd":914,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L878-L914","documentation":"setCredentialsProviderClassName(String) tries to load and instantiate the named class as a HikariCredentialsProvider via reflection (createInstance). Any failure — class not found, no no-arg constructor, wrong type, constructor/static-init exception — is wrapped in a RuntimeException 'Failed to instantiate class <name>'. This fails at configuration time so a broken credentials provider never silently degrades to default credentials.","triggerScenarios":"Passing a class name that is not on the classpath; the class exists but does not implement HikariCredentialsProvider; the class has no public no-arg constructor (e.g. only a constructor taking arguments); the constructor throws (e.g. tries to read a secret that is unavailable at config time).","commonSituations":"Custom secret-vault integrations (Vault, AWS Secrets Manager, KMS) where the provider class lives in another module not shipped with the app; refactoring renaming the provider class without updating config; providers whose constructor does I/O that fails in restricted environments; fat-jar classloader issues.","solutions":["Verify the fully-qualified class name matches the deployed artifact exactly (no typos, right package)","Ensure the class is public, implements HikariCredentialsProvider, and has a public no-arg constructor; move any I/O out of the constructor into the provider's fetch method","Confirm the module/jar containing the provider is on the runtime classpath","Inspect the wrapped cause in the stack trace — it states the real reason (ClassNotFoundException vs NoSuchMethodException vs constructor exception)","Alternatively, construct the provider yourself and use setCredentialsProvider(instance) to get compile-time safety"],"exampleFix":"// before\nconfig.setCredentialsProviderClassName(\"com.acme.VaultCredsProvider\"); // not on classpath -> RuntimeException\n\n// after: build it programmatically instead of by name\nHikariCredentialsProvider p = new com.acme.VaultCredsProvider(vaultClient);\nconfig.setCredentialsProvider(p);","handlingStrategy":"try-catch","validationCode":"try {\n   Class.forName(providerClassName).asSubclass(com.zaxxer.hikari.HikariCredentialsProvider.class)\n       .getConstructor().newInstance();\n} catch (ReflectiveOperationException e) {\n   throw new IllegalStateException(\"Credentials provider unusable: \" + providerClassName, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n   config.setCredentialsProviderClassName(cls);\n} catch (RuntimeException e) {\n   throw new BeanCreationException(\"Failed to init credentials provider \" + cls + \": \" + e.getCause().getMessage(), e);\n}","preventionTips":["Prefer setCredentialsProvider(instance) over the class-name variant for compile-time safety","Keep provider constructors side-effect free; fetch secrets lazily in the provider method","Add an integration test that boots the pool with the real provider in CI"],"tags":["hikaricp","configuration","credentials","reflection","classloading"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}