apache/seatunnel · error · SeaTunnelException

Cannot find unique plugin jar for pluginIdentifier: %s -> %s

Error message

Cannot find unique plugin jar for pluginIdentifier: %s -> %s. Possible impact jar: %s

What it means

selectPluginJar requires a unique matching jar for non-CDC plugins. When the name-matched candidate URLs count is not exactly 1, it throws SeaTunnelException listing all target plugin files, because it cannot pick which jar to load.

Source

Thrown at seatunnel-plugin-discovery/src/main/java/org/apache/seatunnel/plugin/discovery/AbstractPluginDiscovery.java:540

                && StringUtils.startsWithIgnoreCase(pathname.getName(), pluginJarPrefix);
    }

    private Optional<List<URL>> selectPluginJar(
            File[] targetPluginFiles, String pluginJarPrefix, String pluginName, PluginType type) {
        List<URL> resMatchedUrls = new ArrayList<>();
        for (File file : targetPluginFiles) {
            Optional<URL> matchedUrl = findMatchingUrl(file, type, pluginName);
            matchedUrl.ifPresent(resMatchedUrls::add);
        }
        if (pluginName.contains("cdc")) {
            if (resMatchedUrls.size() != 2) {
                throw new SeaTunnelException(
                        String.format(
                                "Cannot find plugin jar for pluginIdentifier: %s -> %s. Possible impact jar: %s",
                                pluginName, pluginJarPrefix, Arrays.asList(targetPluginFiles)));
            }
        } else if (resMatchedUrls.size() != 1) {
            throw new SeaTunnelException(
                    String.format(
                            "Cannot find unique plugin jar for pluginIdentifier: %s -> %s. Possible impact jar: %s",
                            pluginName, pluginJarPrefix, Arrays.asList(targetPluginFiles)));
        }
        return Optional.of(resMatchedUrls);
    }

    private Optional<URL> findMatchingUrl(File file, PluginType type, String pluginName) {
        Map<PluginIdentifier, String> pluginInstanceMap = null;
        switch (type) {
            case SINK:
                pluginInstanceMap = sinkPluginInstance;
                break;
            case SOURCE:
                pluginInstanceMap = sourcePluginInstance;
                break;
            case TRANSFORM:
                pluginInstanceMap = transformPluginInstance;

View on GitHub (pinned to cf67b549a7)

Solutions

1. If zero matches: install the connector with sh bin/install-plugin.sh or download the jar into $SEATUNNEL_HOME/connectors
2. If multiple matches: delete stale/duplicate versions so exactly one jar matches the plugin identifier
3. Keep connector jar filenames in the standard connector-<name>-<version>.jar format

Example fix

// before: ambiguous
connectors/connector-kafka-2.3.0.jar
connectors/connector-kafka-2.3.12.jar
// after
rm connectors/connector-kafka-2.3.0.jar

ls $SEATUNNEL_HOME/connectors | grep "connector-<name>-"
# expect exactly one line; if zero, install it; if multiple, delete stale versions

When it happens

Trigger: findPluginJarPath resolves a plugin whose name does not contain 'cdc' and resMatchedUrls.size() != 1 — either zero matches (jar not installed) or multiple matches (duplicate connector jars).

Common situations: Connector jar not downloaded at all; two versions of the same connector jar in the connectors dir; a fat/uber jar plus the original both matching the plugin prefix.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Can not find any plugin(source/sink/transform) in the dir: %
• Cannot find plugin jar for pluginIdentifier: %s -> %s. Possi
• maxLines must be >= 1
• Plugin %s not found.
• Plugin instance: %s is not supported.

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