{"record":{"id":"28c30e5688b5ff3c","repo":"apache/seatunnel","slug":"class-not-found","errorCode":"CLASS_NOT_FOUND","errorMessage":"Failed to load [","messagePattern":"Failed to load \\[","errorType":"error_code","errorClass":"JdbcConnectorException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/connection/DataSourceUtils.java","lineNumber":146,"sourceCode":"                            .filter(\n                                    each ->\n                                            each.getName().equalsIgnoreCase(setterMethodName)\n                                                    && 1 == each.getParameterTypes().length)\n                            .findFirst();\n        }\n        return methodOptional;\n    }\n\n    private static Object loadDataSource(final String xaDataSourceClassName) {\n        Class<?> xaDataSourceClass;\n        try {\n            xaDataSourceClass =\n                    Thread.currentThread().getContextClassLoader().loadClass(xaDataSourceClassName);\n        } catch (final ClassNotFoundException ignored) {\n            try {\n                xaDataSourceClass = Class.forName(xaDataSourceClassName);\n            } catch (final ClassNotFoundException ex) {\n                throw new JdbcConnectorException(\n                        CommonErrorCodeDeprecated.CLASS_NOT_FOUND,\n                        \"Failed to load [\" + xaDataSourceClassName + \"]\",\n                        ex);\n            }\n        }\n        try {\n            return xaDataSourceClass.getDeclaredConstructor().newInstance();\n        } catch (final ReflectiveOperationException ex) {\n            throw new JdbcConnectorException(\n                    CommonErrorCodeDeprecated.REFLECT_CLASS_OPERATION_FAILED,\n                    \"Failed to instance [\" + xaDataSourceClassName + \"]\",\n                    ex);\n        }\n    }\n}\n","sourceCodeStart":128,"sourceCodeEnd":162,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/connection/DataSourceUtils.java#L128-L162","documentation":"Thrown by DataSourceUtils.loadDataSource when the configured XA datasource class cannot be found: first via the thread context classloader, then via Class.forName, both raising ClassNotFoundException. Wrapped as a JdbcConnectorException with CLASS_NOT_FOUND including the class name in the message.","triggerScenarios":"xa_data_source_url / xaDataSourceClassName references a class not on the classpath — e.g. MySQL XADataSource, MariaDB XADataSource, or Oracle XADataSource class missing because the driver jar is not installed in the connector/plugin directory.","commonSituations":"Driver jar not placed in $SEATUNNEL_HOME/connectors or the plugin dir; wrong xaDataSourceClassName spelling; using a driver version where the class was renamed/moved packages; shaded classloader not seeing the driver.","solutions":["Add the correct JDBC driver jar to the SeaTunnel connector/plugin lib directory","Verify xaDataSourceClassName spelling, e.g. com.mysql.cj.jdbc.MysqlXADataSource","Align the driver version with the database and connector expectation","Check for classloader/shading conflicts if the jar is present but still not loaded"],"exampleFix":"// before\nxa_data_source_url = \"com.vendor.NonexistentXADataSource\"\n// after\nxa_data_source_url = \"com.mysql.cj.jdbc.MysqlXADataSource\"","handlingStrategy":"try-catch","validationCode":"// check class availability before building datasource\ntry { Class.forName(\"com.mysql.cj.jdbc.MysqlXADataSource\"); } catch (ClassNotFoundException e) { /* install driver jar */ }","typeGuard":null,"tryCatchPattern":"try { DataSourceUtils.dataSource(xaClassName, props); } catch (JdbcConnectorException e) {\n  if (CommonErrorCodeDeprecated.CLASS_NOT_FOUND.equals(e.getCode())) { /* load driver jar or fix class name */ }\n}","preventionTips":["Ship the JDBC driver jar in the connector/plugin lib directory","Copy-paste xaDataSourceClassName exactly from driver docs","Pin compatible driver versions per database","Verify classpath in the execution environment, not just the dev box"],"tags":["jdbc","xa","classpath","driver"],"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-14T05:17:10.506Z"}