{"record":{"id":"fef4fe0cfb1495fc","repo":"brettwooldridge/HikariCP","slug":"failed-to-load-driver-class-driverclassname","errorCode":null,"errorMessage":"Failed to load driver class ${driverClassName}","messagePattern":"Failed to load driver class (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":510,"sourceCode":"      checkIfSealed();\n      dataSourceProperties.putAll(dsProperties);\n   }\n\n   public String getDriverClassName()\n   {\n      return driverClassName;\n   }\n\n   public void setDriverClassName(String driverClassName)\n   {\n      checkIfSealed();\n\n      try {\n         createInstance(driverClassName, java.sql.Driver.class);\n         this.driverClassName = driverClassName;\n      }\n      catch (Exception e) {\n         throw new RuntimeException(\"Failed to load driver class \" + driverClassName, e);\n      }\n   }\n\n   public String getJdbcUrl()\n   {\n      return jdbcUrl;\n   }\n\n   public void setJdbcUrl(String jdbcUrl)\n   {\n      checkIfSealed();\n      this.jdbcUrl = jdbcUrl;\n   }\n\n   /**\n    * Get the default auto-commit behavior of connections in the pool.\n    *\n    * @return the default auto-commit behavior of connections","sourceCodeStart":492,"sourceCodeEnd":528,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L492-L528","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the correct JDBC driver dependency matching your database version (e.g. org.postgresql:postgresql, mysql:mysql-connector-j)","Verify the exact class name for your driver version (com.mysql.cj.jdbc.Driver for Connector/J 8+)","Confirm the driver jar is on the runtime classpath, not just compile scope — check the deployed artifact, not only the IDE","If on a container/OSGi runtime, ensure the driver is visible to the classloader that loaded HikariCP","Consider using jdbcUrl alone — many drivers self-register via ServiceLoader and driverClassName is often unnecessary"],"exampleFix":"// before\nconfig.setDriverClassName(\"com.mysql.jdbc.Driver\"); // RuntimeException: failed to load\n\n// after\nconfig.setDriverClassName(\"com.mysql.cj.jdbc.Driver\");\n// plus pom.xml: <dependency>\n//   <groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId>\n// </dependency>","handlingStrategy":"validation","validationCode":"String driver = \"org.postgresql.Driver\";\ntry {\n   Class.forName(driver).asSubclass(java.sql.Driver.class);\n} catch (ClassNotFoundException e) {\n   throw new IllegalStateException(\"JDBC driver not on classpath: \" + driver, e);\n}\nconfig.setDriverClassName(driver);","typeGuard":null,"tryCatchPattern":"try {\n   config.setDriverClassName(driverClass);\n} catch (RuntimeException e) {\n   throw new BeanCreationException(\"Cannot load JDBC driver '\" + driverClass + \"' — check the driver dependency and class name\", e);\n}","preventionTips":["Pin the JDBC driver dependency in build files next to the database version","Prefer jdbcUrl-only config — modern drivers self-register and driverClassName is usually unnecessary","Add a startup connectivity smoke test so classpath problems surface with a clear message","Use driver-class-name constants, not strings scattered across config"],"tags":["hikaricp","configuration","jdbc-driver","classpath","classloading"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}