{"record":{"id":"cecd69303bec567b","repo":"apache/seatunnel","slug":"no-suitable-driver","errorCode":"NO_SUITABLE_DRIVER","errorMessage":"No suitable driver found for the configured JDBC URL","messagePattern":"No suitable driver found for the configured JDBC URL","errorType":"error_code","errorClass":"JdbcConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/connection/SimpleJdbcConnectionProvider.java","lineNumber":115,"sourceCode":"    @Override\n    public Connection getOrEstablishConnection() throws SQLException, ClassNotFoundException {\n        if (isConnectionValid()) {\n            return connection;\n        }\n        Driver driver = getLoadedDriver();\n        Properties info = new Properties();\n        if (jdbcConfig.getUsername().isPresent()) {\n            info.setProperty(\"user\", jdbcConfig.getUsername().get());\n        }\n        if (jdbcConfig.getPassword().isPresent()) {\n            info.setProperty(\"password\", jdbcConfig.getPassword().get());\n        }\n        info.putAll(jdbcConfig.getProperties());\n        connection = driver.connect(jdbcConfig.getUrl(), info);\n        if (connection == null) {\n            // Throw same exception as DriverManager.getConnection when no driver found to match\n            // caller expectation.\n            throw new JdbcConnectorException(\n                    JdbcConnectorErrorCode.NO_SUITABLE_DRIVER,\n                    \"No suitable driver found for the configured JDBC URL\");\n        }\n\n        connection.setAutoCommit(jdbcConfig.isAutoCommit());\n\n        return connection;\n    }\n\n    @Override\n    public void closeConnection() {\n        try {\n            if (isConnectionValid()) {\n                connection.close();\n            }\n        } catch (SQLException e) {\n            LOG.warn(\"JDBC connection close failed.\", e);\n        } finally {","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/connection/SimpleJdbcConnectionProvider.java#L97-L133","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check that the JDBC URL prefix matches the configured driver's database (jdbc:mysql with MySQL driver, jdbc:postgresql with PostgreSQL, etc.)","Print/verify the effective url and driverName in your config; fix the mismatch","Validate the URL format against the driver documentation (some drivers need extra sub-parameters)","If the driver is optional-loaded, ensure the intended driver jar is actually on the classpath so the right Driver instance is used"],"exampleFix":"// before\nurl = \"jdbc:mysql://localhost:3306/db\"\ndriver_name = \"org.postgresql.Driver\"\n// after\nurl = \"jdbc:postgresql://localhost:5432/db\"\ndriver_name = \"org.postgresql.Driver\"","handlingStrategy":"validation","validationCode":"String url = cfg.getUrl();\nMap<String,String> prefixToDriver = Map.of(\n    \"jdbc:mysql:\", \"com.mysql.cj.jdbc.Driver\",\n    \"jdbc:postgresql:\", \"org.postgresql.Driver\",\n    \"jdbc:oracle:\", \"oracle.jdbc.OracleDriver\");\nprefixToDriver.forEach((p, d) -> {\n    if (url.startsWith(p) && !d.equals(cfg.getDriverName()))\n        throw new IllegalArgumentException(\"URL \" + p + \"... requires driver \" + d + \" but got \" + cfg.getDriverName());\n});","typeGuard":"boolean urlMatchesDriver(String url, String driverClass) {\n    String p = url != null && url.startsWith(\"jdbc:\") ? url.substring(5, url.indexOf(':', 5) + 1) : \"\";\n    switch (p) {\n        case \"mysql:\":   return driverClass.startsWith(\"com.mysql\");\n        case \"postgresql:\": return driverClass.startsWith(\"org.postgresql\");\n        case \"oracle:\":  return driverClass.startsWith(\"oracle\");\n        default: return true; // unknown scheme: check manually\n    }\n}","tryCatchPattern":"try {\n    connection = provider.getOrEstablishConnection();\n} catch (JdbcConnectorException e) {\n    if (e.getErrorCode() == JdbcConnectorErrorCode.NO_SUITABLE_DRIVER) {\n        LOG.error(\"Driver {} rejects URL {}; verify scheme/driver match\", driverName, url);\n    }\n    throw e;\n}","preventionTips":["Always derive the URL from the same database docs page as the driver","Copy URL templates from the driver's official documentation, not other projects","Add a pre-flight connect check in CI with the exact url+driver pair","Log the effective url at INFO before connecting to spot copy-paste errors"],"tags":["jdbc","driver","url","connection"],"backgroundTag":"invalid-url","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}