{"record":{"id":"7217ae88cfa4cbaf","repo":"apache/druid","slug":"cannot-load-jdbc-driver-class-driverclassname","errorCode":null,"errorMessage":"Cannot load JDBC driver class '<driverClassName>'","messagePattern":"Cannot load JDBC driver class '<driverClassName>'","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"critical","filePath":"server/src/main/java/org/apache/druid/metadata/BasicDataSourceExt.java","lineNumber":138,"sourceCode":"          try {\n            if (getDriverClassLoader() == null) {\n              driverFromCCL = Class.forName(getDriverClassName());\n            } else {\n              driverFromCCL = Class.forName(\n                  getDriverClassName(), true, getDriverClassLoader());\n            }\n          }\n          catch (ClassNotFoundException cnfe) {\n            driverFromCCL = Thread.currentThread(\n            ).getContextClassLoader().loadClass(\n                getDriverClassName());\n          }\n        }\n        catch (Exception t) {\n          String message = \"Cannot load JDBC driver class '\" +\n                           getDriverClassName() + \"'\";\n          LOGGER.error(t, message);\n          throw new SQLException(message, t);\n        }\n      }\n\n      try {\n        if (driverFromCCL == null) {\n          driverToUse = DriverManager.getDriver(getUrl());\n        } else {\n          // Usage of DriverManager is not possible, as it does not\n          // respect the ContextClassLoader\n          // N.B. This cast may cause ClassCastException which is handled below\n          driverToUse = (Driver) driverFromCCL.newInstance();\n          if (!driverToUse.acceptsURL(getUrl())) {\n            throw new SQLException(\"No suitable driver\", \"08001\");\n          }\n        }\n      }\n      catch (Exception t) {\n        String message = \"Cannot create JDBC driver of class '\" +","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/metadata/BasicDataSourceExt.java#L120-L156","documentation":"BasicDataSourceExt.createConnectionFactory attempts to load the configured JDBC driver class via the context classloader. If Class.forName/driver loading throws, it wraps the cause in SQLException('Cannot load JDBC driver class <driverClassName>'). This means the driver jar is missing or the class name is wrong.","triggerScenarios":"Metadata storage configured with a driverClassName that cannot be instantiated/loaded: wrong class name, missing JDBC driver jar on the classpath, or driver static initialization failure (e.g. ClassNotFoundException, NoClassDefFoundError, driver version incompatibility).","commonSituations":"Forgetting to bundle the PostgreSQL/MySQL JDBC driver extension in the Druid extensions load list; typo in driver class name (e.g. org.postgresql.Driver misspelled); driver jar version conflicts after upgrade.","solutions":["Add the JDBC driver extension to druid.extensions.loadList (e.g. druid-postgresql, mysql-metadata-storage) so the driver jar is on the classpath","Verify druid.metadata.storage.connector.driverClassName matches the actual driver class in the bundled jar","Check the logged root cause (ClassNotFoundException vs linkage/error) and align the driver version with the database server"],"exampleFix":"// before\ndruid.extensions.loadList=[]\ndruid.metadata.storage.connector.driverClassName=com.mysql.cj.jdbc.Driver\n// after\ndruid.extensions.loadList=[\"druid-mysql-metadata-storage\"]\ndruid.metadata.storage.connector.driverClassName=com.mysql.cj.jdbc.Driver","handlingStrategy":"try-catch","validationCode":"try { Class.forName(driverClassName, true, Thread.currentThread().getContextClassLoader()); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"JDBC driver not on classpath: \" + driverClassName); }","typeGuard":null,"tryCatchPattern":"try { dataSource.getConnection(); } catch (SQLException e) { if (e.getMessage() != null && e.getMessage().startsWith(\"Cannot load JDBC driver class\")) { log.error(\"JDBC driver missing; check druid.extensions.loadList and driver jar\"); } throw e; }","preventionTips":["Include the JDBC driver extension (druid-postgresql / druid-mysql-metadata-storage) in the extensions loadList","Verify the driver class name against the driver jar version","Smoke-test DB connectivity at startup before accepting tasks"],"tags":["java","jdbc","classpath","driver-loading"],"backgroundTag":"class-not-found","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}