{"record":{"id":"eae45e3bf246c344","repo":"apache/seatunnel","slug":"create-driver-failed","errorCode":"CREATE_DRIVER_FAILED","errorMessage":"Fail to create driver of class ","messagePattern":"Fail to create driver of class ","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":83,"sourceCode":"    private static Driver loadDriver(String driverName) throws ClassNotFoundException {\n        checkNotNull(driverName);\n        Enumeration<Driver> drivers = DriverManager.getDrivers();\n        while (drivers.hasMoreElements()) {\n            Driver driver = drivers.nextElement();\n            if (driver.getClass().getName().equals(driverName)) {\n                return driver;\n            }\n        }\n\n        // We could reach here for reasons:\n        // * Class loader hell of DriverManager(see JDK-8146872).\n        // * driver is not installed as a service provider.\n        Class<?> clazz =\n                Class.forName(driverName, true, Thread.currentThread().getContextClassLoader());\n        try {\n            return (Driver) clazz.getDeclaredConstructor().newInstance();\n        } catch (Exception ex) {\n            throw new JdbcConnectorException(\n                    JdbcConnectorErrorCode.CREATE_DRIVER_FAILED,\n                    \"Fail to create driver of class \" + driverName,\n                    ex);\n        }\n    }\n\n    protected Driver getLoadedDriver() throws SQLException, ClassNotFoundException {\n        if (loadedDriver == null) {\n            loadedDriver = loadDriver(jdbcConfig.getDriverName());\n        }\n        return loadedDriver;\n    }\n\n    @Override\n    public Connection getOrEstablishConnection() throws SQLException, ClassNotFoundException {\n        if (isConnectionValid()) {\n            return connection;\n        }","sourceCodeStart":65,"sourceCodeEnd":101,"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#L65-L101","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the class name is a java.sql.Driver implementation (e.g. com.mysql.cj.jdbc.Driver, org.postgresql.Driver)","Ship the complete driver jar with all its dependencies in the SeaTunnel classpath","Read the caused-by chain of the wrapped exception and fix the driver's construction failure","Use the driver class name matching your driver version"],"exampleFix":"// before\nurl = \"jdbc:postgresql://host:5432/db\"\ndriver_name = \"org.postgresql.ds.PGSimpleDataSource\"  # not a Driver\n// after\ndriver_name = \"org.postgresql.Driver\"","handlingStrategy":"validation","validationCode":"try {\n    Class<?> c = Class.forName(cfg.getDriverName(), true, Thread.currentThread().getContextClassLoader());\n    if (!java.sql.Driver.class.isAssignableFrom(c))\n        throw new IllegalArgumentException(cfg.getDriverName() + \" does not implement java.sql.Driver\");\n} catch (ClassNotFoundException e) {\n    throw new IllegalArgumentException(\"Driver not on classpath: \" + cfg.getDriverName(), e);\n}","typeGuard":"boolean isLoadableDriver(String name) {\n    try {\n        return java.sql.Driver.class.isAssignableFrom(\n            Class.forName(name, true, Thread.currentThread().getContextClassLoader()));\n    } catch (Throwable t) { return false; }\n}","tryCatchPattern":"try {\n    connection = connectionProvider.getOrEstablishConnection();\n} catch (JdbcConnectorException e) {\n    if (e.getErrorCode() == JdbcConnectorErrorCode.CREATE_DRIVER_FAILED) {\n        LOG.error(\"Cannot construct driver {}; check jar completeness and caused-by\", driverName, e.getCause());\n    }\n    throw e;\n}","preventionTips":["Use only java.sql.Driver implementation class names in driver_name","Ensure driver jars and their transitive dependencies are fully deployed","Test driver instantiation locally with the same JVM/classpath layout","Keep a driver-name/version compatibility matrix for your pipeline"],"tags":["jdbc","driver","reflection","classpath"],"backgroundTag":"class-not-found","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}