apache/flink · error · IllegalStateException

No valid command-line found.

Error message

No valid command-line found.

What it means

Thrown by CliFrontend.validateAndGetActiveCommandLine when none of the registered CustomCommandLine implementations (DefaultCLI, YarnSessionCli, KubernetesSessionCli, etc.) report isActive(commandLine) as true for the parsed arguments. Each custom CLI checks whether its specific options (e.g., -m for standalone, -yarn for YARN, -Dkubernetes.* for K8s) are present and consistent. If none match, Flink cannot determine which deployment backend to use. It is an IllegalStateException (unchecked).

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/cli/CliFrontend.java:1463

    //  Custom command-line
    // --------------------------------------------------------------------------------------------

    /**
     * Gets the custom command-line for the arguments.
     *
     * @param commandLine The input to the command-line.
     * @return custom command-line which is active (may only be one at a time)
     */
    public CustomCommandLine validateAndGetActiveCommandLine(CommandLine commandLine) {
        LOG.debug("Custom commandlines: {}", customCommandLines);
        for (CustomCommandLine cli : customCommandLines) {
            LOG.debug(
                    "Checking custom commandline {}, isActive: {}", cli, cli.isActive(commandLine));
            if (cli.isActive(commandLine)) {
                return cli;
            }
        }
        throw new IllegalStateException("No valid command-line found.");
    }

    /**
     * Loads a class from the classpath that implements the CustomCommandLine interface.
     *
     * @param className The fully-qualified class name to load.
     * @param params The constructor parameters
     */
    private static CustomCommandLine loadCustomCommandLine(String className, Object... params)
            throws Exception {

        Class<? extends CustomCommandLine> customCliClass =
                Class.forName(className).asSubclass(CustomCommandLine.class);

        // construct class types from the parameters
        Class<?>[] types = new Class<?>[params.length];
        for (int i = 0; i < params.length; i++) {
            checkNotNull(params[i], "Parameters for custom command-lines may not be null.");

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Use -m/--target to specify the deployment target explicitly (e.g., -m yarn, -m kubernetes-session, -m <host>:<port>)
2. Ensure the appropriate connector jars (flink-yarn, flink-kubernetes) are in FLINK_HOME/lib or on the classpath so the corresponding CustomCommandLine implementations are discoverable
3. Avoid mixing deployment-specific options from different backends in the same command

Example fix

# before (ambiguous, no CLI activates)
flink run -Dkubernetes.cluster-id=my-cluster -m yarn-session ./job.jar

# after (pick one backend)
flink run -m kubernetes-session -Dkubernetes.cluster-id=my-cluster ./job.jar

// Before deploying, verify at least one custom CLI will activate:
boolean anyActive = customCommandLines.stream().anyMatch(cli -> cli.isActive(commandLine));
if (!anyActive) {
    throw new IllegalArgumentException(
        "No deployment backend matched. Set -m/--target and avoid mixing backend options.");
}

try {
    CustomCommandLine active = cliFrontend.validateAndGetActiveCommandLine(commandLine);
} catch (IllegalStateException e) {
    System.err.println("No deployment CLI activated. Check -m/--target and connector JARs.");
    throw e;
}

When it happens

Trigger: Passing conflicting or incomplete options that no single custom CLI recognizes as a valid active configuration; mixing options from different deployment backends (e.g., partial YARN + partial Kubernetes flags); running with a custom CLI plugin that was not loaded via service discovery.

Common situations: User provides -m with a value but also sets -Dkubernetes.cluster-id, causing both K8s and standalone CLIs to consider themselves non-active due to ambiguity; the flink-dist is missing the YARN or K8s connector jars from its lib/ directory, so the respective custom CLIs are never registered.

Related errors

• No cluster id was specified. Please specify a cluster to whi
• The configuration directory '{}', specified in the '{}' envi
• The configuration directory was not specified. Please specif
• Bad syntax for classpath: {}
• The parallelism must be a positive number: {}

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