apache/seatunnel · error · RuntimeException

Failed to load MySQL JDBC driver

Error message

Failed to load MySQL JDBC driver

What it means

StarRocksSinkWriter.applySchemaChange needs the MySQL JDBC driver (StarRocks exposes a MySQL protocol endpoint) to push schema changes. The writer calls Class.forName("com.mysql.cj.jdbc.Driver") at construction and throws a raw RuntimeException if the driver class is absent from the classpath. This is a packaging/dependency problem, not a connection failure.

Source

Thrown at seatunnel-connectors-v2/connector-starrocks/src/main/java/org/apache/seatunnel/connectors/seatunnel/starrocks/sink/StarRocksSinkWriter.java:95

        try {
            record = serializer.serialize(element);
        } catch (Exception e) {
            throw CommonError.seatunnelRowSerializeFailed(element.toString(), e);
        }
        manager.write(record);
    }

    @Override
    public void applySchemaChange(SchemaChangeEvent event) {
        this.tableSchema = tableSchemaChangeEventDispatcher.reset(tableSchema).apply(event);
        SeaTunnelRowType seaTunnelRowType = tableSchema.toPhysicalRowDataType();
        this.serializer = createSerializer(sinkConfig, seaTunnelRowType);
        this.manager = new StarRocksSinkManager(sinkConfig, tableSchema);

        try {
            Class.forName("com.mysql.cj.jdbc.Driver");
        } catch (ClassNotFoundException e) {
            throw new RuntimeException("Failed to load MySQL JDBC driver", e);
        }

        try (Connection conn =
                DriverManager.getConnection(
                        sinkConfig.getJdbcUrl(),
                        sinkConfig.getUsername(),
                        sinkConfig.getPassword())) {
            SchemaUtils.applySchemaChange(event, conn, sinkTablePath);
        } catch (SQLException e) {
            throw new CatalogException(
                    String.format("Failed connecting to %s via JDBC.", sinkConfig.getJdbcUrl()), e);
        }
    }

    /**
     * Exposes the resolved StarRocks target table so shared-sink schema changes can be broadcast to
     * every sibling writer that commits to the same physical table.
     */

View on GitHub (pinned to cf67b549a7)

Solutions

1. Place mysql-connector-j (8.x) jar in the SeaTunnel connectors/plugin lib directory and restart the job.
2. Re-run `sh bin/install-plugin.sh` to restore the JDBC driver dependency for the connector.
3. If building a custom distro, include the mysql driver artifact in the shaded/fat jar instead of excluding it.

Example fix

// before (pom.xml excludes driver in assembly)
<exclude>com.mysql:mysql-connector-j</exclude>
// after
<include>com.mysql:mysql-connector-j</include>

// Verify driver presence before starting the job
try {
    Class.forName("com.mysql.cj.jdbc.Driver");
    System.out.println("MySQL JDBC driver OK");
} catch (ClassNotFoundException e) {
    System.err.println("Add mysql-connector-j jar to SeaTunnel plugin lib");
}

function isDriverOnClasspath() {
  try { Class.forName("com.mysql.cj.jdbc.Driver"); return true; } catch (ClassNotFoundException e) { return false; }
}

try {
    writer = new StarRocksSinkWriter(sinkConfig, rowType, ...);
} catch (RuntimeException e) {
    if (e.getMessage().equals("Failed to load MySQL JDBC driver")) {
        // deploy mysql-connector-j jar to the connectors lib dir
    }
}

When it happens

Trigger: Starting a StarRocks sink job with schema-change support where the connector jar was deployed without the mysql-connector-java/mysql-connector-j driver jar on the classpath, so Class.forName("com.mysql.cj.jdbc.Driver") throws ClassNotFoundException.

Common situations: Running with a slim connector install where install-plugin.sh did not fetch the JDBC driver; custom FatJAR assembly that excluded mysql driver due to license/dependency exclusions; upgrading the driver to an artifact that changed the class name (pre-8.0 drivers use com.mysql.jdbc.Driver).

Related errors

• Failed to load JDBC driver {}
• Failed to load JDBC driver {}
• Failed to load JDBC driver {}
• DRIVER_NOT_FOUND
• CONNECT_FAILED

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