apache/seatunnel · error · IllegalStateException

deploy mode not support : ${MODE}

Error message

deploy mode not support : ${MODE}

What it means

Common.appRootDir() resolves the SeaTunnel installation root based on the active DeployMode (client/cluster/run-application). If MODE holds a value the switch does not recognize, it throws IllegalStateException naming the unsupported mode.

Source

Thrown at seatunnel-common/src/main/java/org/apache/seatunnel/common/config/Common.java:122

            try {
                String path =
                        Common.class
                                .getProtectionDomain()
                                .getCodeSource()
                                .getLocation()
                                .toURI()
                                .getPath();
                path = new File(path).getPath();
                return Paths.get(path).getParent().getParent();
            } catch (URISyntaxException e) {
                throw new RuntimeException(e);
            }
        } else if (DeployMode.CLUSTER == MODE) {
            return Paths.get("");
        } else if (DeployMode.RUN_APPLICATION == MODE) {
            return Paths.get(FLINK_YARN_APPLICATION_PATH);
        } else {
            throw new IllegalStateException("deploy mode not support : " + MODE);
        }
    }

    public static Path appStarterDir() {
        return appRootDir().resolve("starter");
    }

    /** Plugin Root Dir */
    public static Path pluginRootDir() {
        return Paths.get(getSeaTunnelHome(), "plugins");
    }

    /** Plugin Connector Dir */
    public static Path connectorDir() {
        return Paths.get(getSeaTunnelHome(), "connectors");
    }

    /** lib Dir */

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set the deploy mode to a valid value: client, cluster, or run-application (e.g. -Dseatunnel.deploy.mode=client or the -e/-m/-a CLI flag)
2. Check for typos/case in the mode property being passed to the JVM
3. If embedding SeaTunnel, explicitly initialize Common with a supported DeployMode before resolving paths

Example fix

// before
java -Dseatunnel.deploy.mode=claster ... # typo
// after
java -Dseatunnel.deploy.mode=cluster ...

String mode = System.getProperty("seatunnel.deploy.mode");
if (mode != null && !Set.of("client","cluster","run-application").contains(mode)) throw new IllegalArgumentException("bad mode: " + mode);

try { Path root = Common.appRootDir(); } catch (IllegalStateException e) { // fall back to explicit SEATUNNEL_HOME }

When it happens

Trigger: Calling Common.appRootDir() (directly or via getSeaTunnelHome, appStarterDir, pluginTarball) when the -Dse... deploy mode system property was set to something other than CLIENT, CLUSTER, or RUN_APPLICATION.

Common situations: Typo or wrong-case value in the deploy mode property when launching from a custom launcher or test; an uninitialized MODE (default not applied) in embedded usage; custom deployment scripts passing an invented mode name.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Server property {} must contain at least one absolute execut
• No agent.yaml found. Use --config /path/to/agent.yaml, set E
• Agent config file not found: ${normalized}
• prepare method is not supported
• Option not be null.

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