apache/seatunnel · warning

Failed to load JDBC driver {}

Error message

Failed to load JDBC driver {}

What it means

JdbcSink's constructor attempts Class.forName(driverName) to register the JDBC driver with DriverManager and logs a WARN (not a throw) if the driver class cannot be loaded. This is a best-effort pre-check; failure typically means the driver jar is not on the classpath. The sink proceeds but connection attempts will later fail with 'No suitable driver'.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/sink/JdbcSink.java:100

    private final DataSaveMode dataSaveMode;

    private final SchemaSaveMode schemaSaveMode;

    private final CatalogTable catalogTable;

    public JdbcSink(
            ReadonlyConfig config,
            JdbcSinkConfig jdbcSinkConfig,
            JdbcDialect dialect,
            SchemaSaveMode schemaSaveMode,
            DataSaveMode dataSaveMode,
            CatalogTable catalogTable) {
        // Load the JDBC driver in to DriverManager
        try {
            Class.forName(jdbcSinkConfig.getJdbcConnectionConfig().getDriverName());
        } catch (Exception e) {
            log.warn(
                    "Failed to load JDBC driver {}",
                    jdbcSinkConfig.getJdbcConnectionConfig().getDriverName(),
                    e);
        }
        this.config = config;
        this.jdbcSinkConfig = jdbcSinkConfig;
        this.dialect = dialect;
        this.schemaSaveMode = schemaSaveMode;
        this.dataSaveMode = dataSaveMode;
        this.catalogTable = catalogTable;
        this.tableSchema = catalogTable.getTableSchema();
    }

    @Override
    public String getPluginName() {
        return "Jdbc";
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Place the driver jar in $SEATUNNEL_HOME/plugins/jdbc/lib (or connector lib dir) on all nodes and restart the cluster
2. Correct the driver-name option in the JDBC sink config to the fully-qualified class shipped in the jar
3. Use a shaded driver if the default conflicts with other jars on the classpath
4. Verify the jar actually loads by checking startup logs or jar listing in the lib directory

Example fix

# before
sink {
  Jdbc {
    driver_name = "com.mysql.cj.jdbc.Driver"  # jar missing
  }
}
# after
cp mysql-connector-j-8.x.jar $SEATUNNEL_HOME/plugins/jdbc/lib/
# restart cluster; warn disappears

try {
    Class.forName("com.mysql.cj.jdbc.Driver");
    System.out.println("driver OK");
} catch (ClassNotFoundException e) {
    System.out.println("add driver jar to $SEATUNNEL_HOME/plugins/jdbc/lib");
}

try {
    Class.forName(driverName);
} catch (ClassNotFoundException e) {
    throw new IllegalArgumentException("JDBC driver not on classpath: " + driverName, e);
}

When it happens

Trigger: Constructing JdbcSink with a driverName whose class is absent from the plugin classpath — missing driver jar in $SEATUNNEL_HOME/plugins/jdbc/lib or connectors classpath.

Common situations: Driver jar not downloaded via install-plugin.sh; wrong driver class name in url/driver config (e.g. com.mysql.jdbc.Driver vs com.mysql.cj.jdbc.Driver); running Zeta cluster where only worker nodes have the jar.

Related errors

• DRIVER_NOT_FOUND
• CONNECT_FAILED
• CLASS_NOT_FOUND
• CREATE_DRIVER_FAILED
• LOAD_DRIVER_FAILED

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