alibaba/druid · error · SQLException

jdbc-driver's class not found. '{className}'

Error message

jdbc-driver's class not found. '{className}'

What it means

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.

Source

Thrown at core/src/main/java/com/alibaba/druid/proxy/DruidDriver.java:256

            {
                config.setJmxOption(value);
            }
            restUrl = restUrl.substring(colonPos + 1);
        }
        config.setRawUrl(restUrl);
        if (config.getRawDriverClassName() == null || config.getRawDriverClassName().isEmpty()) {
            String rawDriverClassname = JdbcUtils.getDriverClassName(restUrl);
            config.setRawDriverClassName(rawDriverClassname);
        }
        config.setUrl(url);
        return config;
    }

    public static Driver createDriver(final String className) throws SQLException {
        Class<?> rawDriverClass = Utils.loadClass(className);

        if (rawDriverClass == null) {
            throw new SQLException("jdbc-driver's class not found. '" + className + "'");
        }

        Driver rawDriver;
        try {
            rawDriver = (Driver) rawDriverClass.newInstance();
        } catch (InstantiationException e) {
            throw new SQLException("create driver instance error, driver className '" + className + "'", e);
        } catch (IllegalAccessException e) {
            throw new SQLException("create driver instance error, driver className '" + className + "'", e);
        }

        return rawDriver;
    }

    @Override
    public int getMajorVersion() {
        return this.majorVersion;
    }

View on GitHub (pinned to fa8dc99126)

Solutions

1. Add the missing JDBC driver jar to the application classpath (Maven/Gradle dependency).
2. Verify the rawDriverClassName value is correct and fully-qualified; print it at startup to catch typos and nulls.
3. 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).

Example fix

// before (pom.xml missing the driver)
// url: jdbc:wrap-druid://...
DriverManager.getConnection(url); // -> 'jdbc-driver's class not found. com.mysql.cj.jdbc.Driver'

// after
// pom.xml:
// <dependency>
//   <groupId>mysql</groupId>
//   <artifactId>mysql-connector-java</artifactId>
//   <version>8.0.33</version>
// </dependency>

String cn = config.getRawDriverClassName();
if (cn == null || cn.isEmpty() || Utils.loadClass(cn) == null) {
    throw new IllegalStateException("JDBC driver class '" + cn + "' is not on the classpath");
}

public static boolean driverLoadable(String className) {
    return className != null && !className.isEmpty() && Utils.loadClass(className) != null;
}

try {
    Driver d = DruidDriver.createDriver(className);
} catch (SQLException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("jdbc-driver's class not found")) {
        // add the driver jar, then retry
        throw new IllegalStateException("add the JDBC driver dependency: " + className, e);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• create driver instance error, driver className '{className}'
• create driver instance error, driver className '
• load managed jdbc driver event listener error. {filterName}
• ConfigLoader only support DruidDataSource
• Config DataSource error.

AI-assisted analysis of alibaba/druid@fa8dc99126 (2026-08-14). Data as JSON: /api/errors/faf41cbc9f8a2377. Report an issue: GitHub.