apache/flink · error · IllegalStateException

Multiple compatible client factories found for: {}.

Error message

Multiple compatible client factories found for:
{}.

What it means

Thrown by DefaultClusterClientServiceLoader.getClusterClientFactory when more than one ClusterClientFactory implementation reports isCompatible(configuration) as true. Flink discovers all factories via Java ServiceLoader and checks each one; if multiple match (e.g., both a YARN and Kubernetes factory consider the config compatible), it cannot unambiguously select one and aborts. The error includes the full configuration map for debugging.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/deployment/DefaultClusterClientServiceLoader.java:83

                    compatibleFactories.add(factory);
                }
            } catch (Throwable e) {
                if (e instanceof NoClassDefFoundError
                        || e.getCause() instanceof NoClassDefFoundError) {
                    LOG.info("Could not load factory due to missing dependencies.");
                } else {
                    throw e;
                }
            }
        }

        if (compatibleFactories.size() > 1) {
            final List<String> configStr =
                    configuration.toMap().entrySet().stream()
                            .map(e -> e.getKey() + "=" + e.getValue())
                            .collect(Collectors.toList());

            throw new IllegalStateException(
                    "Multiple compatible client factories found for:\n"
                            + String.join("\n", configStr)
                            + ".");
        }

        if (compatibleFactories.isEmpty()) {
            throw new IllegalStateException(
                    "No ClusterClientFactory found. If you were targeting a Yarn cluster, "
                            + "please make sure to export the HADOOP_CLASSPATH environment variable or have hadoop in your "
                            + "classpath. For more information refer to the \"Deployment\" section of the official "
                            + "Apache Flink documentation.");
        }

        return (ClusterClientFactory<ClusterID>) compatibleFactories.get(0);
    }

    @Override
    public Stream<String> getApplicationModeTargetNames() {

View on GitHub (pinned to 2f3c205e92)

Solutions

  1. Set execution.target explicitly to disambiguate the deployment backend
  2. Remove conflicting connector JARs from the classpath (only include the one deployment backend you intend to use)
  3. Review the configuration map printed in the error message to identify overlapping keys

Example fix

// before (ambiguous config)
config.set("execution.target", "yarn");
config.set("kubernetes.cluster-id", "my-cluster");  // confuses K8s factory

// after
config.set("execution.target", "yarn");
// remove Kubernetes-specific keys
Defensive patterns

Strategy: validation

Validate before calling

// Before calling getClusterClientFactory, verify config targets one backend:
String target = configuration.get(DeploymentOptions.TARGET);
if (target == null || target.isBlank()) {
    throw new IllegalArgumentException(
        "Set execution.target to disambiguate the deployment backend.");
}

Try / catch

try {
    ClusterClientFactory<?> factory = serviceLoader.getClusterClientFactory(config);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Multiple compatible")) {
        System.err.println("Multiple factories matched. Set execution.target explicitly.");
    }
    throw e;
}

Prevention

When it happens

Trigger: Setting configuration keys that make the config simultaneously compatible with multiple deployment backends (e.g., having both YARN and Kubernetes related settings); having multiple factory JARs on the classpath that overlap in their isCompatible logic; a misconfigured or duplicate SPI registration.

Common situations: Custom factory implementations with overly broad isCompatible checks; classpath pollution from multiple Flink connector distributions; experimental or custom deployment plugins that conflict with built-in factories.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/42bac5d6348edcdc. Report an issue: GitHub.