{"record":{"id":"960cd702e0e07905","repo":"apache/seatunnel","slug":"failed-to-load-mysql-jdbc-driver","errorCode":null,"errorMessage":"Failed to load MySQL JDBC driver","messagePattern":"Failed to load MySQL JDBC driver","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-starrocks/src/main/java/org/apache/seatunnel/connectors/seatunnel/starrocks/sink/StarRocksSinkWriter.java","lineNumber":95,"sourceCode":"        try {\n            record = serializer.serialize(element);\n        } catch (Exception e) {\n            throw CommonError.seatunnelRowSerializeFailed(element.toString(), e);\n        }\n        manager.write(record);\n    }\n\n    @Override\n    public void applySchemaChange(SchemaChangeEvent event) {\n        this.tableSchema = tableSchemaChangeEventDispatcher.reset(tableSchema).apply(event);\n        SeaTunnelRowType seaTunnelRowType = tableSchema.toPhysicalRowDataType();\n        this.serializer = createSerializer(sinkConfig, seaTunnelRowType);\n        this.manager = new StarRocksSinkManager(sinkConfig, tableSchema);\n\n        try {\n            Class.forName(\"com.mysql.cj.jdbc.Driver\");\n        } catch (ClassNotFoundException e) {\n            throw new RuntimeException(\"Failed to load MySQL JDBC driver\", e);\n        }\n\n        try (Connection conn =\n                DriverManager.getConnection(\n                        sinkConfig.getJdbcUrl(),\n                        sinkConfig.getUsername(),\n                        sinkConfig.getPassword())) {\n            SchemaUtils.applySchemaChange(event, conn, sinkTablePath);\n        } catch (SQLException e) {\n            throw new CatalogException(\n                    String.format(\"Failed connecting to %s via JDBC.\", sinkConfig.getJdbcUrl()), e);\n        }\n    }\n\n    /**\n     * Exposes the resolved StarRocks target table so shared-sink schema changes can be broadcast to\n     * every sibling writer that commits to the same physical table.\n     */","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-starrocks/src/main/java/org/apache/seatunnel/connectors/seatunnel/starrocks/sink/StarRocksSinkWriter.java#L77-L113","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Place mysql-connector-j (8.x) jar in the SeaTunnel connectors/plugin lib directory and restart the job.","Re-run `sh bin/install-plugin.sh` to restore the JDBC driver dependency for the connector.","If building a custom distro, include the mysql driver artifact in the shaded/fat jar instead of excluding it."],"exampleFix":"// before (pom.xml excludes driver in assembly)\n<exclude>com.mysql:mysql-connector-j</exclude>\n// after\n<include>com.mysql:mysql-connector-j</include>","handlingStrategy":"validation","validationCode":"// Verify driver presence before starting the job\ntry {\n    Class.forName(\"com.mysql.cj.jdbc.Driver\");\n    System.out.println(\"MySQL JDBC driver OK\");\n} catch (ClassNotFoundException e) {\n    System.err.println(\"Add mysql-connector-j jar to SeaTunnel plugin lib\");\n}","typeGuard":"function isDriverOnClasspath() {\n  try { Class.forName(\"com.mysql.cj.jdbc.Driver\"); return true; } catch (ClassNotFoundException e) { return false; }\n}","tryCatchPattern":"try {\n    writer = new StarRocksSinkWriter(sinkConfig, rowType, ...);\n} catch (RuntimeException e) {\n    if (e.getMessage().equals(\"Failed to load MySQL JDBC driver\")) {\n        // deploy mysql-connector-j jar to the connectors lib dir\n    }\n}","preventionTips":["Always install the JDBC driver jar alongside the StarRocks connector (install-plugin.sh).","If building a custom distro, verify the mysql driver is not excluded from the assembly.","Smoke-test driver loading before submitting schema-evolution jobs."],"tags":["jdbc","classpath","starrocks","driver-loading"],"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-14T16:17:12.679Z"}