brettwooldridge/HikariCP · critical · RuntimeException

Failed to get driver instance for jdbcUrl={}

Error message

Failed to get driver instance for jdbcUrl={}

What it means

When no explicit driver class is set, DriverDataSource asks DriverManager.getDriver(jdbcUrl); if no registered driver accepts the URL, the SQLException is wrapped in RuntimeException 'Failed to get driver instance'. It means the JDBC driver for that URL is absent from the classpath or not registered.

Source

Thrown at src/main/java/com/zaxxer/hikari/util/DriverDataSource.java:120

                  LOGGER.warn("Failed to create instance of driver class {}, trying jdbcUrl resolution", driverClassName, e);
               }
            }
         }
      }

      final var sanitizedUrl = maskPasswordInJdbcUrl(jdbcUrl);

      try {
         if (driver == null) {
            driver = DriverManager.getDriver(jdbcUrl);
            LOGGER.debug("Loaded driver with class name {} for jdbcUrl={}", driver.getClass().getName(), sanitizedUrl);
         }
         else if (!driver.acceptsURL(jdbcUrl)) {
            throw new RuntimeException("Driver " + driverClassName + " claims to not accept jdbcUrl, " + sanitizedUrl);
         }
      }
      catch (SQLException e) {
         throw new RuntimeException("Failed to get driver instance for jdbcUrl=" + sanitizedUrl, e);
      }
   }

   @Override
   public Connection getConnection() throws SQLException
   {
      return driver.connect(jdbcUrl, driverProperties);
   }

   @Override
   public Connection getConnection(final String username, final String password) throws SQLException
   {
      final var cloned = (Properties) driverProperties.clone();
      if (username != null) {
         cloned.put(USER, username);
         if (cloned.containsKey("username")) {
            cloned.put("username", username);
         }

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Add the matching JDBC driver dependency to the runtime classpath
2. Fix the jdbcUrl scheme/typo (jdbc:mysql://, jdbc:postgresql://, ...); test with DriverManager.getDriver(url) in isolation
3. If shading, ensure META-INF/services/java.sql.Driver is merged; or set driverClassName explicitly so HikariCP instantiates the driver directly
4. In restrictive classloaders, load the driver via Class.forName(driverClassName, true, appClassLoader) before pool start or set driverClassName

Example fix

# before: url uses postgres, no pg driver on classpath
url=jdbc:postgresql://db:5432/app

# after: add the driver
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.7.3</version>
</dependency>

try {
    java.sql.Driver d = DriverManager.getDriver(jdbcUrl);
} catch (SQLException e) {
    throw new IllegalStateException("No JDBC driver on classpath for " + jdbcUrl, e);
}

When it happens

Trigger: jdbcUrl with a family whose driver jar is not on the classpath; driver jar present but auto-registration removed (SPI file missing, shaded jar, explicit exclusion); malformed jdbcUrl no driver matches (e.g. jdcb: typo); DriverManager visibility issues in modular/stacked classloaders (driver loaded by child loader invisible to DriverManager).

Common situations: Missing dependency after slimming a Docker image, fat-jar shading breaking META-INF/services/java.sql.Driver, OSGi/app-server classloader isolation, typo in URL scheme.

Related errors

• Driver {} claims to not accept jdbcUrl, {}
• Failed to load driver class ${driverClassName}
• Cannot find property file: ${propertyFileName}
• Failed to load class ${className}
• Invalid transaction isolation value: ${transactionIsolationN

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