apache/dolphinscheduler · error · SQLException

Failed to instantiate driver: " + jdbcDriverClassName

Error message

Failed to instantiate driver: " + jdbcDriverClassName

What it means

JdbcDriverConnectionProvider.getConnection wraps ReflectiveOperationException (Class.forName / newInstance failure) from loading the JDBC driver class into SQLException 'Failed to instantiate driver: <class>'.

Source

Thrown at dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-api/src/main/java/org/apache/dolphinscheduler/plugin/datasource/api/datasource/JdbcDriverConnectionProvider.java:49

    private final String jdbcUrl;
    private final String username;
    private final String password;
    private final Properties properties;

    @Override
    public Connection getConnection() throws SQLException {
        try {
            Driver driver = (Driver) Class.forName(jdbcDriverClassName).getDeclaredConstructor().newInstance();
            Properties p = new Properties(properties);
            if (username != null) {
                p.setProperty("user", username);
            }
            if (password != null) {
                p.setProperty("password", password);
            }
            return driver.connect(jdbcUrl, p);
        } catch (ReflectiveOperationException e) {
            throw new SQLException("Failed to instantiate driver: " + jdbcDriverClassName, e);
        }
    }
}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Verify the driver class name against the driver version you deploy
2. Add the JDBC driver jar to the plugin's lib directory / classpath
3. Use the modern driver class (e.g. com.mysql.cj.jdbc.Driver for Connector/J 8+)
4. Check the DataSourcePluginManager loaded the plugin containing the driver

Example fix

// before
param.setDriverClassName("com.mysql.jdbc.Driver");
// after
param.setDriverClassName("com.mysql.cj.jdbc.Driver");

try { Class.forName(driverClassName); } catch (ClassNotFoundException e) { throw new IllegalStateException("driver jar missing: " + driverClassName); }

try { Connection c = provider.getConnection(...); } catch (SQLException e) { if (e.getMessage().startsWith("Failed to instantiate driver")) { /* fix driver classpath/name */ } }

When it happens

Trigger: The configured driver class name is wrong, or the driver jar is not on the classpath of the datasource plugin.

Common situations: 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.

Related errors

• DATASOURCE_CONNECT_FAILED
• GET_DATASOURCE_TABLES_ERROR
• Create adhoc connection error
• Other params include possible malicious keys.
• datasource other params: + entry.getKey() + illegal

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/80522cc1dbd35e2c. Report an issue: GitHub.