{"record":{"id":"fc8af5d4fefeb35f","repo":"brettwooldridge/HikariCP","slug":"failed-to-get-driver-instance-for-jdbcurl","errorCode":null,"errorMessage":"Failed to get driver instance for jdbcUrl={}","messagePattern":"Failed to get driver instance for jdbcUrl=(.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"src/main/java/com/zaxxer/hikari/util/DriverDataSource.java","lineNumber":120,"sourceCode":"                  LOGGER.warn(\"Failed to create instance of driver class {}, trying jdbcUrl resolution\", driverClassName, e);\n               }\n            }\n         }\n      }\n\n      final var sanitizedUrl = maskPasswordInJdbcUrl(jdbcUrl);\n\n      try {\n         if (driver == null) {\n            driver = DriverManager.getDriver(jdbcUrl);\n            LOGGER.debug(\"Loaded driver with class name {} for jdbcUrl={}\", driver.getClass().getName(), sanitizedUrl);\n         }\n         else if (!driver.acceptsURL(jdbcUrl)) {\n            throw new RuntimeException(\"Driver \" + driverClassName + \" claims to not accept jdbcUrl, \" + sanitizedUrl);\n         }\n      }\n      catch (SQLException e) {\n         throw new RuntimeException(\"Failed to get driver instance for jdbcUrl=\" + sanitizedUrl, e);\n      }\n   }\n\n   @Override\n   public Connection getConnection() throws SQLException\n   {\n      return driver.connect(jdbcUrl, driverProperties);\n   }\n\n   @Override\n   public Connection getConnection(final String username, final String password) throws SQLException\n   {\n      final var cloned = (Properties) driverProperties.clone();\n      if (username != null) {\n         cloned.put(USER, username);\n         if (cloned.containsKey(\"username\")) {\n            cloned.put(\"username\", username);\n         }","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/util/DriverDataSource.java#L102-L138","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Add the matching JDBC driver dependency to the runtime classpath","Fix the jdbcUrl scheme/typo (jdbc:mysql://, jdbc:postgresql://, ...); test with DriverManager.getDriver(url) in isolation","If shading, ensure META-INF/services/java.sql.Driver is merged; or set driverClassName explicitly so HikariCP instantiates the driver directly","In restrictive classloaders, load the driver via Class.forName(driverClassName, true, appClassLoader) before pool start or set driverClassName"],"exampleFix":"# before: url uses postgres, no pg driver on classpath\nurl=jdbc:postgresql://db:5432/app\n\n# after: add the driver\n<dependency>\n  <groupId>org.postgresql</groupId>\n  <artifactId>postgresql</artifactId>\n  <version>42.7.3</version>\n</dependency>","handlingStrategy":"validation","validationCode":"try {\n    java.sql.Driver d = DriverManager.getDriver(jdbcUrl);\n} catch (SQLException e) {\n    throw new IllegalStateException(\"No JDBC driver on classpath for \" + jdbcUrl, e);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Declare the JDBC driver dependency explicitly","When shading, merge META-INF/services/java.sql.Driver","Set driverClassName explicitly in restrictive classloader setups","Validate the URL scheme at startup"],"tags":["hikaricp","jdbc","driver","classpath","configuration"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}