alibaba/druid · error · SQLException

create driver instance error, driver className '{className}'

Error message

create driver instance error, driver className '{className}'

What it means

DruidDriver.createDriver(className) catches InstantiationException when calling rawDriverClass.newInstance() — the driver class was loaded but could not be instantiated. InstantiationException specifically means the class is abstract, an interface, an array, a primitive, or void, or has no accessible no-arg constructor. The original InstantiationException is chained as the cause, so its message clarifies which condition applies.

Source

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

            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;
    }

    @Override
    public int getMinorVersion() {
        return this.minorVersion;
    }

    @Override

View on GitHub (pinned to fa8dc99126)

Solutions

Set rawDriverClassName to the concrete, public, no-arg-constructible driver class (the one registered in the driver's META-INF/services).
Inspect the chained InstantiationException cause for the exact reason (abstract / no constructor) and correct accordingly.
If the driver genuinely needs arguments, it is not JDBC-DriverManager-compatible — use a DataSource-based configuration instead of the proxy driver path.

Example fix

// before
// rawDriverClassName = com.mysql.cj.jdbc.MysqlDataSource // not a java.sql.Driver, no no-arg ctor pattern

// after
// rawDriverClassName = com.mysql.cj.jdbc.Driver // implements Driver, public no-arg ctor

Defensive patterns

Strategy: validation

Validate before calling

Class<?> c = Utils.loadClass(className);
if (c != null && (Modifier.isAbstract(c.getModifiers()) || Modifier.isInterface(c.getModifiers()))) {
    throw new IllegalStateException(className + " is abstract/interface; use the concrete Driver class");
}
try { c.getDeclaredConstructor(); } catch (NoSuchMethodException e) {
    throw new IllegalStateException(className + " has no no-arg constructor; not DriverManager-compatible");
}

Type guard

public static boolean instantiableDriver(String className) {
    Class<?> c = Utils.loadClass(className);
    if (c == null) return false;
    int m = c.getModifiers();
    if (Modifier.isAbstract(m) || Modifier.isInterface(m)) return false;
    try { c.getDeclaredConstructor(); return true; } catch (NoSuchMethodException e) { return false; }
}

Try / catch

try {
    Driver d = DruidDriver.createDriver(className);
} catch (SQLException e) {
    if (e.getCause() instanceof InstantiationException) {
        // pointed at an abstract/interface class; switch to the concrete driver
        throw new IllegalStateException("use the concrete driver class, not " + className, e);
    }
    throw e;
}

Prevention

Point rawDriverClassName at the concrete public Driver class listed in the vendor's META-INF/services.
Validate the class is instantiable with a no-arg constructor at boot.
If the driver needs constructor args, use a DataSource-based configuration instead.

When it happens

Trigger: rawDriverClassName resolves to a class that is abstract or lacks a public no-arg constructor — e.g. pointing at a base class, an interface, an inner/protected class, or a driver implementation that requires constructor arguments rather than the JDBC-standard public no-arg constructor.

Common situations: Naming a factory or abstract base class instead of the concrete driver; pointing at an older driver that uses a singleton getInstance() pattern with a private constructor; copy-paste of a wrong/placeholder class name.

Related errors

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