apache/seatunnel · error · IllegalStateException

Multiple DebeziumAdapters matched connector class " + connec

Error message

Multiple DebeziumAdapters matched connector class " + connectorClassName + ": [" + providers + "]. Each connector class must have exactly one adapter.

What it means

DebeziumAdapterFactory.getAdapter resolves the Debezium adapter for a given connector class name. It expects exactly one registered adapter to match; when two or more adapters claim the same connector class it throws IllegalStateException because the mapping between connector class and adapter must be unambiguous. This usually indicates a classpath with duplicate/conflicting connector-cdc adapter jars.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/debezium/DebeziumAdapterFactory.java:93

            throw new IllegalStateException(
                    "No DebeziumAdapter found for connector class: "
                            + connectorClassName
                            + ". Ensure a META-INF/services/"
                            + DebeziumAdapter.class.getName()
                            + " registration is present in the connector module.");
        }

        if (matches.size() > 1) {
            String providers =
                    matches.stream()
                            .map(
                                    a ->
                                            a.getClass().getName()
                                                    + " (Debezium "
                                                    + a.getDebeziumVersion()
                                                    + ")")
                            .collect(Collectors.joining(", "));
            throw new IllegalStateException(
                    "Multiple DebeziumAdapters matched connector class "
                            + connectorClassName
                            + ": ["
                            + providers
                            + "]. Each connector class must have exactly one adapter.");
        }

        DebeziumAdapter adapter = matches.get(0);
        LOG.info(
                "Found DebeziumAdapter for {}: {} targeting Debezium {}",
                connectorClassName,
                adapter.getClass().getName(),
                adapter.getDebeziumVersion());
        return adapter;
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. List the connector plugin directory and remove duplicate/older connector-cdc jar versions so only one remains per connector class
2. Run sh bin/install-plugin.sh to restore a clean, version-consistent set of connectors
3. Check the exception message's provider list (class name + Debezium version) to identify which two jars conflict and remove one
4. If building a custom connector, ensure only one DebeziumAdapter implementation registers support for that connector class (ServiceLoader file)

Example fix

// before
plugins/
  connector-cdc-mysql-2.3.x.jar
  connector-cdc-mysql-2.3.10.jar  // duplicate -> Multiple DebeziumAdapters matched
// after
plugins/
  connector-cdc-mysql-2.3.10.jar

// before starting the job, ensure no duplicate connector jars
ls $SEATUNNEL_HOME/connectors | grep -i connector-cdc | sort | uniq -d

try {
    DebeziumAdapter adapter = DebeziumAdapterFactory.getAdapter(connectorClassName);
} catch (IllegalStateException e) {
    // log provider list from message, abort startup with clear remediation hint
    throw new ConfigException("Duplicate CDC adapter registrations; clean the plugin dir", e);
}

When it happens

Trigger: Calling getAdapter(connectorClassName) when the loaded ServiceLoader registry contains two DebeziumAdapters whose supported connector class equals the requested class name, e.g. two versions of the same CDC connector jar on the classpath.

Common situations: Running a SeaTunnel job with duplicate connector-cdc jars in the plugin directory (e.g. both mysql-cdc and a snapshot/older copy, or cdc connectors from different SeaTunnel versions installed together); fat-jar shading that bundles multiple adapter implementations.

Related errors

• Multiple factories for identifier '%s' that implement '%s' f
• DataTypeChanger not reset
• Couldn't initialize type registry
• Could not find any factories that implement '%s' in the clas
• Failed to load JDBC driver com.mysql.cj.jdbc.Driver

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