{"record":{"id":"393978215345f46e","repo":"apache/seatunnel","slug":"multiple-debeziumadapters-matched-connector-class","errorCode":null,"errorMessage":"Multiple DebeziumAdapters matched connector class \" + connectorClassName + \": [\" + providers + \"]. Each connector class must have exactly one adapter.","messagePattern":"Multiple DebeziumAdapters matched connector class \" \\+ connectorClassName \\+ \": \\[\" \\+ providers \\+ \"\\]\\. Each connector class must have exactly one adapter\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/debezium/DebeziumAdapterFactory.java","lineNumber":93,"sourceCode":"            throw new IllegalStateException(\n                    \"No DebeziumAdapter found for connector class: \"\n                            + connectorClassName\n                            + \". Ensure a META-INF/services/\"\n                            + DebeziumAdapter.class.getName()\n                            + \" registration is present in the connector module.\");\n        }\n\n        if (matches.size() > 1) {\n            String providers =\n                    matches.stream()\n                            .map(\n                                    a ->\n                                            a.getClass().getName()\n                                                    + \" (Debezium \"\n                                                    + a.getDebeziumVersion()\n                                                    + \")\")\n                            .collect(Collectors.joining(\", \"));\n            throw new IllegalStateException(\n                    \"Multiple DebeziumAdapters matched connector class \"\n                            + connectorClassName\n                            + \": [\"\n                            + providers\n                            + \"]. Each connector class must have exactly one adapter.\");\n        }\n\n        DebeziumAdapter adapter = matches.get(0);\n        LOG.info(\n                \"Found DebeziumAdapter for {}: {} targeting Debezium {}\",\n                connectorClassName,\n                adapter.getClass().getName(),\n                adapter.getDebeziumVersion());\n        return adapter;\n    }\n}\n","sourceCodeStart":75,"sourceCodeEnd":110,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/debezium/DebeziumAdapterFactory.java#L75-L110","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["List the connector plugin directory and remove duplicate/older connector-cdc jar versions so only one remains per connector class","Run sh bin/install-plugin.sh to restore a clean, version-consistent set of connectors","Check the exception message's provider list (class name + Debezium version) to identify which two jars conflict and remove one","If building a custom connector, ensure only one DebeziumAdapter implementation registers support for that connector class (ServiceLoader file)"],"exampleFix":"// before\nplugins/\n  connector-cdc-mysql-2.3.x.jar\n  connector-cdc-mysql-2.3.10.jar  // duplicate -> Multiple DebeziumAdapters matched\n// after\nplugins/\n  connector-cdc-mysql-2.3.10.jar","handlingStrategy":"validation","validationCode":"// before starting the job, ensure no duplicate connector jars\nls $SEATUNNEL_HOME/connectors | grep -i connector-cdc | sort | uniq -d","typeGuard":null,"tryCatchPattern":"try {\n    DebeziumAdapter adapter = DebeziumAdapterFactory.getAdapter(connectorClassName);\n} catch (IllegalStateException e) {\n    // log provider list from message, abort startup with clear remediation hint\n    throw new ConfigException(\"Duplicate CDC adapter registrations; clean the plugin dir\", e);\n}","preventionTips":["Keep exactly one version of each connector-cdc jar in the connectors directory","Re-run install-plugin.sh after upgrades instead of manually adding jars","Check shaded fat jars for embedded duplicate adapter ServiceLoader registrations"],"tags":["cdc","classpath","duplicate-plugin","initialization"],"backgroundTag":"conflicting-config-options","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"}