apache/seatunnel · error · IllegalArgumentException

SeaTunnel job on spark engine deploy mode only support these

Error message

SeaTunnel job on spark engine deploy mode only support these options: [cluster, client]

What it means

Thrown by SparkCommandArgs' DeployMode converter when the --deploy-mode CLI value is not one of the two Spark deployment modes SeaTunnel supports. The value is parsed into the DeployMode enum, then checked against an allow-list containing only CLUSTER and CLIENT; anything else fails before Spark is ever invoked. This is an early input-validation guard so users get a clear message instead of an obscure Spark error.

Source

Thrown at seatunnel-core/seatunnel-spark-starter/seatunnel-spark-starter-common/src/main/java/org/apache/seatunnel/core/starter/spark/args/SparkCommandArgs.java:83

        }
        return new SparkTaskExecuteCommand(this);
    }

    public static class SparkDeployModeConverter implements IStringConverter<DeployMode> {
        private static final List<DeployMode> DEPLOY_MODE_TYPE_LIST = new ArrayList<>();

        static {
            DEPLOY_MODE_TYPE_LIST.add(DeployMode.CLIENT);
            DEPLOY_MODE_TYPE_LIST.add(DeployMode.CLUSTER);
        }

        @Override
        public DeployMode convert(String value) {
            DeployMode deployMode = DeployMode.valueOf(value.toUpperCase());
            if (DEPLOY_MODE_TYPE_LIST.contains(deployMode)) {
                return deployMode;
            } else {
                throw new IllegalArgumentException(
                        "SeaTunnel job on spark engine deploy mode only "
                                + "support these options: [cluster, client]");
            }
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Change --deploy-mode to either 'cluster' or 'client' (case-insensitive)
2. Remove the --deploy-mode flag entirely to use the default
3. Check for typos or trailing whitespace in the value passed in the shell script or config

Example fix

// before
--deploy-mode yarn-cluster
// after
--deploy-mode cluster

final List<String> ALLOWED = List.of("cluster", "client");
if (deployMode == null || !ALLOWED.contains(deployMode.trim().toLowerCase())) {
    throw new IllegalArgumentException("deploy-mode must be one of: cluster, client");
}

boolean isValidDeployMode(String v) {
    return v != null && List.of("cluster", "client").contains(v.trim().toLowerCase());
}

When it happens

Trigger: Running seatunnel.sh/spark-submit style submission with --deploy-mode set to a value outside [cluster, client], e.g. --deploy-mode local, --deploy-mode yarn-cluster, or a misspelled value like 'cluser'. The value must survive DeployMode.valueOf(value.toUpperCase()) AND be in DEPLOY_MODE_TYPE_LIST.

Common situations: Users copying Flink-style deploy mode values (yarn-cluster, yarn-session, local) into SeaTunnel-on-Spark configs; typos in shell scripts; documentation for older versions mentioning modes SeaTunnel no longer accepts.

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

• --restore and --restore-with-checkpoint are mutually exclusi
• --savepoint and --restore-with-checkpoint are mutually exclu
• --restore-with-checkpoint requires a numeric jobId, got: ${v
• Dry-run mode must not be empty.
• ${name} must be greater than zero.

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