apache/seatunnel · error · IllegalArgumentException

Unsupported deploy mode

Error message

Unsupported deploy mode: ${deployMode}

What it means

IllegalArgumentException thrown by FileUtils.getConfigPath when the deploy mode of the command args is not one of the explicitly handled modes (CLIENT, RUN_APPLICATION, CLUSTER). The switch has no branch for the mode, so the library cannot decide whether to use the config file path as-is or only its file name, and fails fast.

Solutions

  1. Use a supported deploy mode (client, cluster, run-application)
  2. If adding a new DeployMode constant, add a case for it in getConfigPath
  3. Inspect args.getDeployMode() before calling to confirm it is one of CLIENT/RUN_APPLICATION/CLUSTER

Example fix

// before
DeployMode mode = DeployMode.YARN_APPLICATION; // unhandled
// after
args.setDeployMode(DeployMode.CLIENT); // or add a case for the new mode
Defensive patterns

Strategy: type-guard

Validate before calling

if (deployMode != DeployMode.CLIENT && deployMode != DeployMode.CLUSTER && deployMode != DeployMode.RUN_APPLICATION) {
    throw new IllegalArgumentException("Mode not supported by getConfigPath");
}

Type guard

boolean isHandled(DeployMode m) {
    return m == DeployMode.CLIENT || m == DeployMode.CLUSTER || m == DeployMode.RUN_APPLICATION;
}

Try / catch

try {
    path = FileUtils.getConfigPath(args);
} catch (IllegalArgumentException e) {
    log.error("Deploy mode {} not handled", args.getDeployMode(), e);
}

Prevention

When it happens

Trigger: Calling FileUtils.getConfigPath with SeaTunnelCommandArgs whose getDeployMode() returns an unhandled enum value — typically after a new DeployMode enum constant was added without updating this switch, or a null/custom deploy mode injected programmatically.

Common situations: Developers extending the starter with a new deploy mode; tests constructing args with an unusual DeployMode; version upgrades where enum and switch got out of sync.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-core/seatunnel-core-starter/src/main/java/org/apache/seatunnel/core/starter/utils/FileUtils.java:54

    /**
     * Get the seatunnel config path. In client mode, the path to the config file is directly given
     * by user. In cluster mode, the path to the config file is the `executor path/config file
     * name`.
     *
     * @param args args
     * @return path of the seatunnel config file.
     */
    public static Path getConfigPath(@NonNull AbstractCommandArgs args) {
        switch (args.getDeployMode()) {
            case RUN:
            case CLIENT:
                return Paths.get(args.getConfigFile());
            case RUN_APPLICATION:
            case CLUSTER:
                return Paths.get(getFileName(args.getConfigFile()));
            default:
                throw new IllegalArgumentException(
                        "Unsupported deploy mode: " + args.getDeployMode());
        }
    }

    /**
     * Check whether the conf file exists.
     *
     * @param configFile the path of the config file
     */
    public static void checkConfigExist(Path configFile) {
        if (!configFile.toFile().exists()) {
            throw CommonError.fileNotExistFailed("SeaTunnel", "read", configFile.toString());
        }
    }

    /**
     * Get the file name from the given path. e.g. seatunnel/conf/config.conf -> config.conf
     *

View on GitHub (pinned to cf67b549a7)