apache/seatunnel · critical · JdbcConnectorException

CLASS_NOT_FOUND

CLASS_NOT_FOUND

Error message

Failed to load [

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/connection/DataSourceUtils.java:146

                            .filter(
                                    each ->
                                            each.getName().equalsIgnoreCase(setterMethodName)
                                                    && 1 == each.getParameterTypes().length)
                            .findFirst();
        }
        return methodOptional;
    }

    private static Object loadDataSource(final String xaDataSourceClassName) {
        Class<?> xaDataSourceClass;
        try {
            xaDataSourceClass =
                    Thread.currentThread().getContextClassLoader().loadClass(xaDataSourceClassName);
        } catch (final ClassNotFoundException ignored) {
            try {
                xaDataSourceClass = Class.forName(xaDataSourceClassName);
            } catch (final ClassNotFoundException ex) {
                throw new JdbcConnectorException(
                        CommonErrorCodeDeprecated.CLASS_NOT_FOUND,
                        "Failed to load [" + xaDataSourceClassName + "]",
                        ex);
            }
        }
        try {
            return xaDataSourceClass.getDeclaredConstructor().newInstance();
        } catch (final ReflectiveOperationException ex) {
            throw new JdbcConnectorException(
                    CommonErrorCodeDeprecated.REFLECT_CLASS_OPERATION_FAILED,
                    "Failed to instance [" + xaDataSourceClassName + "]",
                    ex);
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add the correct JDBC driver jar to the SeaTunnel connector/plugin lib directory
2. Verify xaDataSourceClassName spelling, e.g. com.mysql.cj.jdbc.MysqlXADataSource
3. Align the driver version with the database and connector expectation
4. Check for classloader/shading conflicts if the jar is present but still not loaded

Example fix

// before
xa_data_source_url = "com.vendor.NonexistentXADataSource"
// after
xa_data_source_url = "com.mysql.cj.jdbc.MysqlXADataSource"

// check class availability before building datasource
try { Class.forName("com.mysql.cj.jdbc.MysqlXADataSource"); } catch (ClassNotFoundException e) { /* install driver jar */ }

try { DataSourceUtils.dataSource(xaClassName, props); } catch (JdbcConnectorException e) {
  if (CommonErrorCodeDeprecated.CLASS_NOT_FOUND.equals(e.getCode())) { /* load driver jar or fix class name */ }
}

When it happens

Trigger: 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.

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

Related errors

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

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