apache/seatunnel · error · IllegalStateException

No DebeziumAdapter found for connector class: " + connectorC

Error message

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

What it means

DebeziumAdapterFactory discovers DebeziumAdapter implementations via Java SPI (ServiceLoader) and picks one that supports the target Debezium connector class. When no registered adapter supports the connector class name, it throws IllegalStateException instructing the user to add a META-INF/services/<DebeziumAdapter FQCN> registration in the connector module.

Source

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

     * @param classLoader the class loader used to discover {@link DebeziumAdapter} registrations
     *     from {@code META-INF/services}
     * @throws IllegalStateException if no matching adapter is found, or if more than one adapter
     *     matches
     */
    public static DebeziumAdapter getAdapter(String connectorClassName, ClassLoader classLoader) {
        LOG.info("Loading DebeziumAdapter for connector class: {}", connectorClassName);
        ServiceLoader<DebeziumAdapter> loader =
                ServiceLoader.load(DebeziumAdapter.class, classLoader);

        List<DebeziumAdapter> matches = new ArrayList<>();
        for (DebeziumAdapter adapter : loader) {
            if (adapter.supports(connectorClassName)) {
                matches.add(adapter);
            }
        }

        if (matches.isEmpty()) {
            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(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Create/restore META-INF/services/<DebeziumAdapter FQCN> listing your adapter implementation in the connector module's resources
2. Verify the SPI file survives packaging (use ServicesResourceTransformer when shading)
3. Check the connector class name in the message matches the Debezium module you actually use
4. Upgrade SeaTunnel if support for your database was added in a newer release

Example fix

// before
src/main/resources/ (no META-INF/services file)
// after
src/main/resources/META-INF/services/org.apache.seatunnel.connectors.cdc.base.debezium.DebeziumAdapter
containing: org.apache.seatunnel.connectors.cdc.mysql.debezium.MysqlDebeziumAdapter

ServiceLoader<DebeziumAdapter> loader = ServiceLoader.load(DebeziumAdapter.class);
List<DebeziumAdapter> adapters = new ArrayList<>();
loader.forEach(adapters::add);
if (adapters.stream().noneMatch(a -> a.supports(connectorClassName))) {
    throw new IllegalStateException("No DebeziumAdapter for " + connectorClassName);
}

try {
    DebeziumAdapter adapter = DebeziumAdapterFactory.getAdapter(connectorClassName);
} catch (IllegalStateException e) {
    LOG.error("SPI registration missing: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Building/sourcing a CDC connector (e.g. a custom database) whose Debezium connector class name is not claimed by any DebeziumAdapter registered under META-INF/services in the deployed plugin jar — or the services file being dropped by shading/assembly config.

Common situations: Writing a custom CDC connector and forgetting the SPI registration file; fat-jar shading excluding META-INF/services; using a Debezium connector type unsupported by the installed SeaTunnel version.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• No data type converter found for identifier: ${identifier}
• No data converter found for identifier: ${identifier}
• No type converter found for identifier: ${identifier}
• Could not find any factories that implement '%s' in the clas
• Could not load service provider for factories.

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