apache/dolphinscheduler · error · IllegalStateException

Duplicate datasource channel named '%s'

Error message

Duplicate datasource channel named '%s'

What it means

Thrown by DataSourcePluginManager when the SPI discovery mechanism finds two DataSourceChannelFactory implementations registered under the same channel name. The manager keeps a map keyed by channel name, so a duplicate would silently overwrite a plugin; it fails fast instead. This indicates a classpath/plugin packaging problem, not a user configuration issue.

Source

Thrown at dolphinscheduler-datasource-plugin/dolphinscheduler-datasource-api/src/main/java/org/apache/dolphinscheduler/plugin/datasource/api/plugin/DataSourcePluginManager.java:68

    }

    public static DataSourceProcessor getDataSourceProcessor(@NonNull DbType dbType) {
        return dataSourceProcessorMap.get(dbType.getName());
    }

    public static void loadDataSourcePlugin() {
        initializeDataSourceChannel();
        initializeDataSourceProcessor();
    }

    private static synchronized void initializeDataSourceChannel() {
        if (MapUtils.isNotEmpty(datasourceChannelMap)) {
            return;
        }
        new PrioritySPIFactory<>(DataSourceChannelFactory.class).getSPIMap().forEach(
                (dataSourceChannelName, dataSourceChannelFactory) -> {
                    if (datasourceChannelMap.containsKey(dataSourceChannelName)) {
                        throw new IllegalStateException(
                                format("Duplicate datasource channel named '%s'", dataSourceChannelName));
                    }
                    datasourceChannelMap.put(dataSourceChannelName, dataSourceChannelFactory.create());
                    log.info("Registered datasource channel: {}", dataSourceChannelName);
                });
    }

    private static synchronized void initializeDataSourceProcessor() {
        if (MapUtils.isNotEmpty(dataSourceProcessorMap)) {
            return;
        }

        ServiceLoader.load(DataSourceProcessor.class).forEach(factory -> {
            final String name = factory.getDbType().getName();
            if (dataSourceProcessorMap.containsKey(name)) {
                throw new IllegalStateException(format("Duplicate datasource processor named '%s'", name));
            }
            DataSourceProcessor dataSourceProcessor = factory.create();

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Find the duplicate: list all jars providing META-INF/services/org.apache.dolphinscheduler.plugin.datasource.api.datasource.DataSourceChannelFactory and identify the duplicated name
2. Remove the redundant/stale plugin jar (e.g. duplicate or old-version jar in the plugins/libs directory)
3. If it is your custom plugin, rename the channel name returned by the factory's name() method to a unique value
4. Rebuild the fat jar with proper SPI merging (e.g. ServicesResourceTransformer in maven-shade-plugin) to deduplicate service files

Example fix

// before (custom plugin factory)
public String getName() { return "mysql"; }
// after
public String getName() { return "mysql-custom-v2"; }

Set<String> seen = new HashSet<>();
for (String f : new File(pluginsDir).list((d,n)->n.endsWith(".jar"))) {
  // scan jar for META-INF/services/...DataSourceChannelFactory names
}
if (seen.contains(myChannelName)) throw new IllegalStateException("name in use: " + myChannelName);

if (datasourceChannelMap.containsKey(dataSourceChannelName)) { log.warn("skipping duplicate channel {}", dataSourceChannelName); return; }

try {
  pluginManager.loadDataSourcePlugin();
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Duplicate datasource channel")) {
    log.error("Duplicate SPI plugin name on classpath: {}", e.getMessage());
  } else throw e;
}

When it happens

Trigger: Calling loadDataSourcePlugin/initializeDataSourceChannel when two jars on the classpath both register a DataSourceChannelFactory with the same SPI name in META-INF/services (or duplicate SPI resource files), or the same plugin jar is loaded twice (e.g. copied into the libs dir twice).

Common situations: Deploying a custom datasource plugin that declares a name already used by a built-in plugin; fat-jar shading that merges duplicate META-INF/services entries; stale plugin jars left over after an upgrade in the plugins directory.

Related errors

• Duplicate datasource processor named '%s'
• 10168
• Failed to instantiate driver: " + jdbcDriverClassName
• Failed to get the product version description file. The file

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/5cf7180f207fd21d. Report an issue: GitHub.