apache/seatunnel · error · JdbcConnectorException

REFLECT_CLASS_OPERATION_FAILED

REFLECT_CLASS_OPERATION_FAILED

Error message

Failed to instance [

What it means

This error is thrown by DataSourceUtils.loadDataSource when instantiating a configured XADataSource class via reflection fails. SeaTunnel locates the xaDataSourceClassName, loads it, and calls getDeclaredConstructor().newInstance(); any ReflectiveOperationException (class not found, no-arg constructor missing, constructor throwing, illegal access) is wrapped in this JdbcConnectorException. It means the driver class could be named but not actually constructed, so XA (exactly-once) JDBC connections cannot be created.

Source

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

    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 plugin/lib directory for the connector
  2. Verify the xaDataSourceClassName exactly matches the driver's XADataSource class for your driver version
  3. Check the wrapped 'Caused by' ReflectiveOperationException for the real cause (missing class, constructor exception, security) and fix that
  4. If upgrading drivers, update the class name (e.g. MySQL 5.x com.mysql.jdbc.Driver -> 8.x com.mysql.cj.jdbc.Driver)

Example fix

// before
url = "jdbc:mysql://localhost:3306/test"
xaDataSourceClassName = "com.mysql.jdbc.Driver"   // wrong: this is a Driver, and 8.x removed it
// after
xaDataSourceClassName = "com.mysql.cj.jdbc.MysqlXADataSource"
Defensive patterns

Strategy: validation

Validate before calling

String cls = cfg.getXaDataSourceClassName();
try {
    Class<?> c = Class.forName(cls, true, Thread.currentThread().getContextClassLoader());
    c.getDeclaredConstructor(); // must have a public no-arg constructor
    if (!javax.sql.XADataSource.class.isAssignableFrom(c)) throw new IllegalStateException(cls + " is not an XADataSource");
} catch (ReflectiveOperationException | IllegalStateException e) {
    throw new IllegalArgumentException("Bad xaDataSourceClassName: " + cls, e);
}

Type guard

boolean isValidXaDataSource(String name) {
    try {
        Class<?> c = Class.forName(name, true, Thread.currentThread().getContextClassLoader());
        return javax.sql.XADataSource.class.isAssignableFrom(c)
            && java.lang.reflect.Modifier.isPublic(c.getModifiers());
    } catch (ClassNotFoundException e) { return false; }
}

Try / catch

try {
    ds = DataSourceUtils.dataSource(jdbcConfig);
} catch (JdbcConnectorException e) {
    if (e.getErrorCode() == CommonErrorCodeDeprecated.REFLECT_CLASS_OPERATION_FAILED) {
        LOG.error("Driver class {} cannot be instantiated; check classpath/driver version", jdbcConfig.getXaDataSourceClassName(), e.getCause());
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling DataSourceUtils.dataSource() with an xaDataSourceClassName whose class is absent from the runtime classpath/plugin dir, whose driver has no public no-arg constructor, or whose constructor throws (e.g. driver init fails due to missing native libs or wrong JDBC URL scheme for that driver).

Common situations: Driver jar not placed in $SEATUNNEL_HOME/connectors or lib directory so Class.forName-style loading partially succeeds but instantiation fails; typo in xaDataSourceClassName (e.g. com.mysql.jdbc.Driver vs com.mysql.cj.jdbc.Driver); using an old driver version removed in a JDBC driver upgrade; shading/classloader isolation preventing driver initialization.

Related errors

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