brettwooldridge/HikariCP · critical · RuntimeException

Failed to instantiate class ${credentialsProviderClassName}

Error message

Failed to instantiate class ${credentialsProviderClassName}

What it means

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.

Source

Thrown at src/main/java/com/zaxxer/hikari/HikariConfig.java:896

      return credentialsProviderClassName;
   }

   /**
    * Set the class name of the {@link HikariCredentialsProvider} that will be used to get credentials at runtime. Use this method
    * or provide a {@link HikariCredentialsProvider} instance via the {@link #setCredentialsProvider(HikariCredentialsProvider)} method.
    *
    * @param credentialsProviderClassName the class name of the credentials provider
    * @see HikariCredentialsProvider
    */
   public void setCredentialsProviderClassName(String credentialsProviderClassName) {
      checkIfSealed();

      try {
         this.credentialsProvider = createInstance(credentialsProviderClassName, HikariCredentialsProvider.class);
         this.exceptionOverrideClassName = credentialsProviderClassName;
      }
      catch (Exception e) {
         throw new RuntimeException("Failed to instantiate class " + credentialsProviderClassName, e);
      }
   }

   /**
    * Get the {@link HikariCredentialsProvider} instance created by {@link #setCredentialsProviderClassName(String)} or specified by
    * {@link #setCredentialsProvider(HikariCredentialsProvider)}.
    *
    * @return the HikariCredentialsProvider instance, or null
    * @see HikariCredentialsProvider
    */
   public HikariCredentialsProvider getCredentialsProvider() {
      return credentialsProvider;
   }

   /**
    * Set a user supplied {@link HikariCredentialsProvider} instance. If this method is used, then the {@link #setCredentialsProviderClassName(String)}
    * method should not be used. The {@link HikariCredentialsProvider} instance will be used to get credentials at runtime.
    *

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Verify the fully-qualified class name matches the deployed artifact exactly (no typos, right package)
2. 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
3. Confirm the module/jar containing the provider is on the runtime classpath
4. Inspect the wrapped cause in the stack trace — it states the real reason (ClassNotFoundException vs NoSuchMethodException vs constructor exception)
5. Alternatively, construct the provider yourself and use setCredentialsProvider(instance) to get compile-time safety

Example fix

// before
config.setCredentialsProviderClassName("com.acme.VaultCredsProvider"); // not on classpath -> RuntimeException

// after: build it programmatically instead of by name
HikariCredentialsProvider p = new com.acme.VaultCredsProvider(vaultClient);
config.setCredentialsProvider(p);

try {
   Class.forName(providerClassName).asSubclass(com.zaxxer.hikari.HikariCredentialsProvider.class)
       .getConstructor().newInstance();
} catch (ReflectiveOperationException e) {
   throw new IllegalStateException("Credentials provider unusable: " + providerClassName, e);
}

try {
   config.setCredentialsProviderClassName(cls);
} catch (RuntimeException e) {
   throw new BeanCreationException("Failed to init credentials provider " + cls + ": " + e.getCause().getMessage(), e);
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Failed to instantiate class ${exceptionOverrideClassName}
• Failed to load class ${className}
• Failed to load driver class ${driverClassName}
• Property %s does not exist on target %s
• connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m

AI-assisted analysis of brettwooldridge/HikariCP@a4d93f4f85 (2026-08-14). Data as JSON: /api/errors/b6c7cdeac382b70e. Report an issue: GitHub.