apache/flink · critical · IllegalStateException

No ClusterClientFactory found. If you were targeting a Yarn

Error message

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.

What it means

Thrown by DefaultClusterClientServiceLoader.getClusterClientFactory when no ClusterClientFactory implementation reports isCompatible(configuration) as true. Flink discovers all factories via Java ServiceLoader; if none match, it cannot determine the deployment target. The error specifically mentions HADOOP_CLASSPATH because the most common cause is YARN deployment without Hadoop libraries on the classpath, which prevents the YARN factory from loading.

Source

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

                    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() {
        final ServiceLoader<ClusterClientFactory> loader =
                ServiceLoader.load(ClusterClientFactory.class);

        final List<String> result = new ArrayList<>();

        final Iterator<ClusterClientFactory> it = loader.iterator();
        while (true) {

View on GitHub (pinned to 2f3c205e92)

Solutions

For YARN: export HADOOP_CLASSPATH=`hadoop classpath` and ensure Hadoop is installed
Set -Dexecution.target=<yarn|kubernetes-session|kubernetes-application|remote> explicitly
Verify the relevant connector JAR (flink-yarn, flink-kubernetes) is in FLINK_HOME/lib/
Ensure Hadoop config files (core-site.xml, yarn-site.xml) are on the classpath or in HADOOP_CONF_DIR

Example fix

# before (no Hadoop on classpath)
flink run -m yarn ./job.jar

# after
export HADOOP_CLASSPATH=`hadoop classpath`
flink run -m yarn ./job.jar

Defensive patterns

Strategy: validation

Validate before calling

// For YARN: verify Hadoop is on the classpath before submitting:
if (config.get(DeploymentOptions.TARGET).contains("yarn")) {
    String hadoopCp = System.getenv("HADOOP_CLASSPATH");
    if (hadoopCp == null || hadoopCp.isBlank()) {
        throw new IllegalStateException(
            "HADOOP_CLASSPATH not set. Run: export HADOOP_CLASSPATH=`hadoop classpath`");
    }
}

Try / catch

try {
    ClusterClientFactory<?> factory = serviceLoader.getClusterClientFactory(config);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("No ClusterClientFactory")) {
        System.err.println("No factory found. Check HADOOP_CLASSPATH and connector JARs.");
    }
    throw e;
}

Prevention

For YARN: always run `export HADOOP_CLASSPATH=\`hadoop classpath\`` before starting Flink
Verify the relevant connector JAR is in FLINK_HOME/lib/
Set -Dexecution.target=<backend> explicitly to guide factory selection

When it happens

Trigger: Targeting YARN but HADOOP_CLASSPATH is not set (no Hadoop JARs available to the YarnClusterClientFactory); targeting a deployment type whose factory JAR is not on the classpath; an empty or minimal classpath that excludes all connector distributions; execution.target not set and no factory's default heuristic matches.

Common situations: Fresh Flink installation without Hadoop configured; running in an environment where Hadoop configs (core-site.xml, yarn-site.xml) are missing; container image that bundles Flink but not Hadoop; targeting Kubernetes but flink-kubernetes JAR is excluded.

Related errors

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