apache/seatunnel · error · JdbcConnectorException

CREATE_DRIVER_FAILED

CREATE_DRIVER_FAILED

Error message

Fail to create driver of class 

What it means

SimpleJdbcConnectionProvider.loadDriver instantiates the configured JDBC Driver class reflectively; if clazz.getDeclaredConstructor().newInstance() fails for any reason, it wraps the exception in JdbcConnectorException with code CREATE_DRIVER_FAILED. This means the driver class was found on the classpath but could not be constructed into a java.sql.Driver instance.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/connection/SimpleJdbcConnectionProvider.java:83

    private static Driver loadDriver(String driverName) throws ClassNotFoundException {
        checkNotNull(driverName);
        Enumeration<Driver> drivers = DriverManager.getDrivers();
        while (drivers.hasMoreElements()) {
            Driver driver = drivers.nextElement();
            if (driver.getClass().getName().equals(driverName)) {
                return driver;
            }
        }

        // We could reach here for reasons:
        // * Class loader hell of DriverManager(see JDK-8146872).
        // * driver is not installed as a service provider.
        Class<?> clazz =
                Class.forName(driverName, true, Thread.currentThread().getContextClassLoader());
        try {
            return (Driver) clazz.getDeclaredConstructor().newInstance();
        } catch (Exception ex) {
            throw new JdbcConnectorException(
                    JdbcConnectorErrorCode.CREATE_DRIVER_FAILED,
                    "Fail to create driver of class " + driverName,
                    ex);
        }
    }

    protected Driver getLoadedDriver() throws SQLException, ClassNotFoundException {
        if (loadedDriver == null) {
            loadedDriver = loadDriver(jdbcConfig.getDriverName());
        }
        return loadedDriver;
    }

    @Override
    public Connection getOrEstablishConnection() throws SQLException, ClassNotFoundException {
        if (isConnectionValid()) {
            return connection;
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Confirm the class name is a java.sql.Driver implementation (e.g. com.mysql.cj.jdbc.Driver, org.postgresql.Driver)
2. Ship the complete driver jar with all its dependencies in the SeaTunnel classpath
3. Read the caused-by chain of the wrapped exception and fix the driver's construction failure
4. Use the driver class name matching your driver version

Example fix

// before
url = "jdbc:postgresql://host:5432/db"
driver_name = "org.postgresql.ds.PGSimpleDataSource"  # not a Driver
// after
driver_name = "org.postgresql.Driver"

try {
    Class<?> c = Class.forName(cfg.getDriverName(), true, Thread.currentThread().getContextClassLoader());
    if (!java.sql.Driver.class.isAssignableFrom(c))
        throw new IllegalArgumentException(cfg.getDriverName() + " does not implement java.sql.Driver");
} catch (ClassNotFoundException e) {
    throw new IllegalArgumentException("Driver not on classpath: " + cfg.getDriverName(), e);
}

boolean isLoadableDriver(String name) {
    try {
        return java.sql.Driver.class.isAssignableFrom(
            Class.forName(name, true, Thread.currentThread().getContextClassLoader()));
    } catch (Throwable t) { return false; }
}

try {
    connection = connectionProvider.getOrEstablishConnection();
} catch (JdbcConnectorException e) {
    if (e.getErrorCode() == JdbcConnectorErrorCode.CREATE_DRIVER_FAILED) {
        LOG.error("Cannot construct driver {}; check jar completeness and caused-by", driverName, e.getCause());
    }
    throw e;
}

When it happens

Trigger: Class.forName succeeds (class present) but newInstance() throws: driver class is not actually a java.sql.Driver (ClassCastException), its constructor throws during static/instance init (e.g. bad system state, missing dependency of the driver jar), or there is no public no-arg constructor.

Common situations: Passing a DataSource or XADataSource class name where a Driver class is expected; partially-present driver jars missing transitive dependencies; driver static initializer throwing due to JVM/security restrictions; wrong class name after driver upgrade.

Related errors

• DRIVER_NOT_FOUND
• CONNECT_FAILED
• CLASS_NOT_FOUND
• REFLECT_CLASS_OPERATION_FAILED
• LOAD_DRIVER_FAILED

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/eae45e3bf246c344. Report an issue: GitHub.