{"record":{"id":"faf41cbc9f8a2377","repo":"alibaba/druid","slug":"jdbc-driver-s-class-not-found-classname","errorCode":null,"errorMessage":"jdbc-driver's class not found. '{className}'","messagePattern":"jdbc-driver's class not found\\. '(.+?)'","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/com/alibaba/druid/proxy/DruidDriver.java","lineNumber":256,"sourceCode":"            {\n                config.setJmxOption(value);\n            }\n            restUrl = restUrl.substring(colonPos + 1);\n        }\n        config.setRawUrl(restUrl);\n        if (config.getRawDriverClassName() == null || config.getRawDriverClassName().isEmpty()) {\n            String rawDriverClassname = JdbcUtils.getDriverClassName(restUrl);\n            config.setRawDriverClassName(rawDriverClassname);\n        }\n        config.setUrl(url);\n        return config;\n    }\n\n    public static Driver createDriver(final String className) throws SQLException {\n        Class<?> rawDriverClass = Utils.loadClass(className);\n\n        if (rawDriverClass == null) {\n            throw new SQLException(\"jdbc-driver's class not found. '\" + className + \"'\");\n        }\n\n        Driver rawDriver;\n        try {\n            rawDriver = (Driver) rawDriverClass.newInstance();\n        } catch (InstantiationException e) {\n            throw new SQLException(\"create driver instance error, driver className '\" + className + \"'\", e);\n        } catch (IllegalAccessException e) {\n            throw new SQLException(\"create driver instance error, driver className '\" + className + \"'\", e);\n        }\n\n        return rawDriver;\n    }\n\n    @Override\n    public int getMajorVersion() {\n        return this.majorVersion;\n    }","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/alibaba/druid/blob/fa8dc9912637a2f729eef9f55356621fec18d40e/core/src/main/java/com/alibaba/druid/proxy/DruidDriver.java#L238-L274","documentation":"DruidDriver.createDriver(className) throws this when Utils.loadClass(className) returns null — i.e. no JDBC driver class with the given name could be loaded by the context classloader. This fires when Druid is acting as a proxy driver (jdbc:wrap-druid:// / DruidDriver) and trying to instantiate the real underlying driver. A null return from loadClass means the class is genuinely absent from the classpath, not merely inaccessible.","triggerScenarios":"Using the Druid proxy/URL-based driver (DruidDriver) with a rawDriverClassName that is not on the classpath; relying on auto-detection (JdbcUtils.getDriverClassName(url)) for a URL whose driver jar is missing; typo in the driver class name in the URL or config.","commonSituations":"Missing JDBC driver dependency (e.g. mysql-connector-java not declared); fat-jar shading that excluded the driver SPI; classloader isolation in web/app servers hiding the driver from Druid's loader; upgraded Druid but not the driver.","solutions":["Add the missing JDBC driver jar to the application classpath (Maven/Gradle dependency).","Verify the rawDriverClassName value is correct and fully-qualified; print it at startup to catch typos and nulls.","If running in a container/app-server, ensure the driver is visible to the classloader Druid uses (often the application loader, not the server lib loader)."],"exampleFix":"// before (pom.xml missing the driver)\n// url: jdbc:wrap-druid://...\nDriverManager.getConnection(url); // -> 'jdbc-driver's class not found. com.mysql.cj.jdbc.Driver'\n\n// after\n// pom.xml:\n// <dependency>\n//   <groupId>mysql</groupId>\n//   <artifactId>mysql-connector-java</artifactId>\n//   <version>8.0.33</version>\n// </dependency>","handlingStrategy":"validation","validationCode":"String cn = config.getRawDriverClassName();\nif (cn == null || cn.isEmpty() || Utils.loadClass(cn) == null) {\n    throw new IllegalStateException(\"JDBC driver class '\" + cn + \"' is not on the classpath\");\n}","typeGuard":"public static boolean driverLoadable(String className) {\n    return className != null && !className.isEmpty() && Utils.loadClass(className) != null;\n}","tryCatchPattern":"try {\n    Driver d = DruidDriver.createDriver(className);\n} catch (SQLException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"jdbc-driver's class not found\")) {\n        // add the driver jar, then retry\n        throw new IllegalStateException(\"add the JDBC driver dependency: \" + className, e);\n    }\n    throw e;\n}","preventionTips":["Declare the JDBC driver as an explicit dependency, not transitive.","Validate the driver class is loadable in a boot check.","In app servers, ensure the driver is on the same classloader as Druid."],"tags":["driver-loading","classpath","proxy-driver","configuration"],"backgroundTag":null,"analyzedSha":"fa8dc9912637a2f729eef9f55356621fec18d40e","analyzedAt":"2026-08-14T04:55:06.789Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}