{"record":{"id":"80522cc1dbd35e2c","repo":"apache/dolphinscheduler","slug":"failed-to-instantiate-driver-jdbcdriverclassn","errorCode":null,"errorMessage":"Failed to instantiate driver: \" + jdbcDriverClassName","messagePattern":"Failed to instantiate driver: \" \\+ jdbcDriverClassName","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-api/src/main/java/org/apache/dolphinscheduler/plugin/datasource/api/datasource/JdbcDriverConnectionProvider.java","lineNumber":49,"sourceCode":"    private final String jdbcUrl;\n    private final String username;\n    private final String password;\n    private final Properties properties;\n\n    @Override\n    public Connection getConnection() throws SQLException {\n        try {\n            Driver driver = (Driver) Class.forName(jdbcDriverClassName).getDeclaredConstructor().newInstance();\n            Properties p = new Properties(properties);\n            if (username != null) {\n                p.setProperty(\"user\", username);\n            }\n            if (password != null) {\n                p.setProperty(\"password\", password);\n            }\n            return driver.connect(jdbcUrl, p);\n        } catch (ReflectiveOperationException e) {\n            throw new SQLException(\"Failed to instantiate driver: \" + jdbcDriverClassName, e);\n        }\n    }\n}\n","sourceCodeStart":31,"sourceCodeEnd":53,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-api/src/main/java/org/apache/dolphinscheduler/plugin/datasource/api/datasource/JdbcDriverConnectionProvider.java#L31-L53","documentation":"JdbcDriverConnectionProvider.getConnection wraps ReflectiveOperationException (Class.forName / newInstance failure) from loading the JDBC driver class into SQLException 'Failed to instantiate driver: <class>'.","triggerScenarios":"The configured driver class name is wrong, or the driver jar is not on the classpath of the datasource plugin.","commonSituations":"Upgrading to a driver where the class was renamed (e.g. com.mysql.jdbc.Driver → com.mysql.cj.jdbc.Driver), missing driver jar in the deployment image, typo in driver class config.","solutions":["Verify the driver class name against the driver version you deploy","Add the JDBC driver jar to the plugin's lib directory / classpath","Use the modern driver class (e.g. com.mysql.cj.jdbc.Driver for Connector/J 8+)","Check the DataSourcePluginManager loaded the plugin containing the driver"],"exampleFix":"// before\nparam.setDriverClassName(\"com.mysql.jdbc.Driver\");\n// after\nparam.setDriverClassName(\"com.mysql.cj.jdbc.Driver\");","handlingStrategy":"try-catch","validationCode":"try { Class.forName(driverClassName); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"driver jar missing: \" + driverClassName); }","typeGuard":null,"tryCatchPattern":"try { Connection c = provider.getConnection(...); } catch (SQLException e) { if (e.getMessage().startsWith(\"Failed to instantiate driver\")) { /* fix driver classpath/name */ } }","preventionTips":["Ship the driver jar with the plugin","Match driver class name to driver version","Verify class name with a Class.forName smoke test at startup"],"tags":["jdbc","classpath","driver"],"backgroundTag":"class-not-found","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}