brettwooldridge/HikariCP · critical · RuntimeException

Failed to load driver class ${driverClassName}

Error message

Failed to load driver class ${driverClassName}

What it means

setDriverClassName(String) immediately attempts to load and instantiate the named class as a java.sql.Driver (via createInstance, i.e. Class.forName + cast). If the class is not on the classpath, is not a Driver, or its static initializer fails, HikariCP wraps the underlying exception in a RuntimeException with the message 'Failed to load driver class <name>'. This surfaces at configuration time rather than first connection, to fail fast on a missing JDBC driver.

Source

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

      checkIfSealed();
      dataSourceProperties.putAll(dsProperties);
   }

   public String getDriverClassName()
   {
      return driverClassName;
   }

   public void setDriverClassName(String driverClassName)
   {
      checkIfSealed();

      try {
         createInstance(driverClassName, java.sql.Driver.class);
         this.driverClassName = driverClassName;
      }
      catch (Exception e) {
         throw new RuntimeException("Failed to load driver class " + driverClassName, e);
      }
   }

   public String getJdbcUrl()
   {
      return jdbcUrl;
   }

   public void setJdbcUrl(String jdbcUrl)
   {
      checkIfSealed();
      this.jdbcUrl = jdbcUrl;
   }

   /**
    * Get the default auto-commit behavior of connections in the pool.
    *
    * @return the default auto-commit behavior of connections

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Add the correct JDBC driver dependency matching your database version (e.g. org.postgresql:postgresql, mysql:mysql-connector-j)
2. Verify the exact class name for your driver version (com.mysql.cj.jdbc.Driver for Connector/J 8+)
3. Confirm the driver jar is on the runtime classpath, not just compile scope — check the deployed artifact, not only the IDE
4. If on a container/OSGi runtime, ensure the driver is visible to the classloader that loaded HikariCP
5. Consider using jdbcUrl alone — many drivers self-register via ServiceLoader and driverClassName is often unnecessary

Example fix

// before
config.setDriverClassName("com.mysql.jdbc.Driver"); // RuntimeException: failed to load

// after
config.setDriverClassName("com.mysql.cj.jdbc.Driver");
// plus pom.xml: <dependency>
//   <groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId>
// </dependency>

String driver = "org.postgresql.Driver";
try {
   Class.forName(driver).asSubclass(java.sql.Driver.class);
} catch (ClassNotFoundException e) {
   throw new IllegalStateException("JDBC driver not on classpath: " + driver, e);
}
config.setDriverClassName(driver);

try {
   config.setDriverClassName(driverClass);
} catch (RuntimeException e) {
   throw new BeanCreationException("Cannot load JDBC driver '" + driverClass + "' — check the driver dependency and class name", e);
}

When it happens

Trigger: setDriverClassName("org.postgresql.Driver") (or the driverClassName property) when the postgres driver jar is missing from the classpath; a typo'd or renamed driver class (e.g. old com.mysql.jdbc.Driver vs com.mysql.cj.jdbc.Driver); driver jar present but its static init throws; class present but does not implement java.sql.Driver.

Common situations: Forgetting the JDBC driver dependency in Spring Boot (Boot no longer adds transitively in some setups); mixing driver and server versions (MySQL Connector/J 8 class rename); shaded/fat jars stripping driver classes; different classloaders in app servers/OSGi where the driver is invisible to HikariCP's loader.

Related errors

• Failed to instantiate class ${credentialsProviderClassName}
• Failed to instantiate class ${exceptionOverrideClassName}
• Cannot find property file: ${propertyFileName}
• Failed to get driver instance for jdbcUrl={}
• Failed to load class ${className}

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