apache/seatunnel · error · JdbcConnectorException

NO_SUITABLE_DRIVER

NO_SUITABLE_DRIVER

Error message

No suitable driver found for the configured JDBC URL

What it means

Thrown in SimpleJdbcConnectionProvider.getOrEstablishConnection when driver.connect(url, info) returns null, meaning the loaded Driver does not accept the configured JDBC URL. Per the JDBC spec, a Driver returns null when the URL scheme is not its own, so SeaTunnel reports that no suitable driver exists for the URL rather than silently proceeding with a null connection.

Source

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

    @Override
    public Connection getOrEstablishConnection() throws SQLException, ClassNotFoundException {
        if (isConnectionValid()) {
            return connection;
        }
        Driver driver = getLoadedDriver();
        Properties info = new Properties();
        if (jdbcConfig.getUsername().isPresent()) {
            info.setProperty("user", jdbcConfig.getUsername().get());
        }
        if (jdbcConfig.getPassword().isPresent()) {
            info.setProperty("password", jdbcConfig.getPassword().get());
        }
        info.putAll(jdbcConfig.getProperties());
        connection = driver.connect(jdbcConfig.getUrl(), info);
        if (connection == null) {
            // Throw same exception as DriverManager.getConnection when no driver found to match
            // caller expectation.
            throw new JdbcConnectorException(
                    JdbcConnectorErrorCode.NO_SUITABLE_DRIVER,
                    "No suitable driver found for the configured JDBC URL");
        }

        connection.setAutoCommit(jdbcConfig.isAutoCommit());

        return connection;
    }

    @Override
    public void closeConnection() {
        try {
            if (isConnectionValid()) {
                connection.close();
            }
        } catch (SQLException e) {
            LOG.warn("JDBC connection close failed.", e);
        } finally {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check that the JDBC URL prefix matches the configured driver's database (jdbc:mysql with MySQL driver, jdbc:postgresql with PostgreSQL, etc.)
2. Print/verify the effective url and driverName in your config; fix the mismatch
3. Validate the URL format against the driver documentation (some drivers need extra sub-parameters)
4. If the driver is optional-loaded, ensure the intended driver jar is actually on the classpath so the right Driver instance is used

Example fix

// before
url = "jdbc:mysql://localhost:3306/db"
driver_name = "org.postgresql.Driver"
// after
url = "jdbc:postgresql://localhost:5432/db"
driver_name = "org.postgresql.Driver"

String url = cfg.getUrl();
Map<String,String> prefixToDriver = Map.of(
    "jdbc:mysql:", "com.mysql.cj.jdbc.Driver",
    "jdbc:postgresql:", "org.postgresql.Driver",
    "jdbc:oracle:", "oracle.jdbc.OracleDriver");
prefixToDriver.forEach((p, d) -> {
    if (url.startsWith(p) && !d.equals(cfg.getDriverName()))
        throw new IllegalArgumentException("URL " + p + "... requires driver " + d + " but got " + cfg.getDriverName());
});

boolean urlMatchesDriver(String url, String driverClass) {
    String p = url != null && url.startsWith("jdbc:") ? url.substring(5, url.indexOf(':', 5) + 1) : "";
    switch (p) {
        case "mysql:":   return driverClass.startsWith("com.mysql");
        case "postgresql:": return driverClass.startsWith("org.postgresql");
        case "oracle:":  return driverClass.startsWith("oracle");
        default: return true; // unknown scheme: check manually
    }
}

try {
    connection = provider.getOrEstablishConnection();
} catch (JdbcConnectorException e) {
    if (e.getErrorCode() == JdbcConnectorErrorCode.NO_SUITABLE_DRIVER) {
        LOG.error("Driver {} rejects URL {}; verify scheme/driver match", driverName, url);
    }
    throw e;
}

When it happens

Trigger: JdbcConfig.url uses a scheme (jdbc:xxx:...) that does not match the configured driver class, or the driver rejects the URL properties; also when driverName is misconfigured so the loaded driver belongs to a different database than the URL.

Common situations: Copy-pasted URL from another database (jdbc:mysql URL with postgres driver); malformed URL missing the expected prefix; driver that requires a different URL format for the version in use; using a generic driver with a database-specific URL.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• NO_SUITABLE_DRIVER
• NO_SUITABLE_DRIVER
• CREATE_DRIVER_FAILED
• The JDBC source statement returned no connection. Closing th
• Failed to get connection, interrupted while doing another at

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