apache/seatunnel · error · SeaTunnelEngineException

Not supported cluster role: ${clusterRole}

Error message

Not supported cluster role: ${clusterRole}

What it means

When starting a SeaTunnel cluster node, the `--role` (cluster role) argument must be one of master, worker, or master_and_worker. ServerExecuteCommand.execute maps the role string onto EngineConfig.ClusterRole and throws SeaTunnelEngineException for any other value. If no role is given it safely defaults to MASTER_AND_WORKER, so this error only occurs on an explicitly wrong value.

Source

Thrown at seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/command/ServerExecuteCommand.java:75

    public void execute() {
        checkEnvironment();
        SeaTunnelConfig seaTunnelConfig = ConfigProvider.locateAndGetSeaTunnelConfig();
        if (this.serverCommandArgs.isShowClusterMembers()) {
            showClusterMembers();
            return;
        }

        String clusterRole = this.serverCommandArgs.getClusterRole();
        if (StringUtils.isNotBlank(clusterRole)) {
            if (EngineConfig.ClusterRole.MASTER.toString().equalsIgnoreCase(clusterRole)) {
                seaTunnelConfig.getEngineConfig().setClusterRole(EngineConfig.ClusterRole.MASTER);
            } else if (EngineConfig.ClusterRole.WORKER.toString().equalsIgnoreCase(clusterRole)) {
                seaTunnelConfig.getEngineConfig().setClusterRole(EngineConfig.ClusterRole.WORKER);

                // in hazelcast lite node will not store IMap data.
                seaTunnelConfig.getHazelcastConfig().setLiteMember(true);
            } else {
                throw new SeaTunnelEngineException("Not supported cluster role: " + clusterRole);
            }
        } else {
            seaTunnelConfig
                    .getEngineConfig()
                    .setClusterRole(EngineConfig.ClusterRole.MASTER_AND_WORKER);
        }

        SeaTunnelServerStarter.createHazelcastInstance(
                seaTunnelConfig, Thread.currentThread().getName());
    }

    private void checkEnvironment() {
        if (isAllocatingThreadGetName()) {
            log.warn(
                    "The current JDK version is not recommended. Please upgrade to JDK 1.8.0_102 or higher. "
                            + "The current version will affect the performance of log printing. "
                            + "For details, please refer to https://issues.apache.org/jira/browse/LOG4J2-2052");
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Use only `-r master`, `-r worker`, or `-r master_and_worker` when starting the cluster
2. Omit the `-r` flag entirely to run a combined master+worker node
3. Update legacy deployment scripts that use old role names from previous SeaTunnel versions
4. Check `seatunnel-cluster.sh --help` for the accepted role values in your version

Example fix

// before
sh bin/seatunnel-cluster.sh -r slave
// after
sh bin/seatunnel-cluster.sh -r worker

Set<String> valid = Set.of("master", "worker", "master_and_worker");
if (clusterRole != null && !valid.contains(clusterRole.toLowerCase())) {
    throw new IllegalArgumentException("-r must be master|worker|master_and_worker");
}

try {
    command.execute(serverCommandArgs);
} catch (SeaTunnelEngineException e) {
    if (e.getMessage().startsWith("Not supported cluster role")) {
        log.error("Use -r master|worker|master_and_worker");
    }
}

When it happens

Trigger: Starting a server node with `seatunnel-cluster.sh -r <value>` where <value> is not master/worker/master_and_worker (case-insensitive), e.g. `-r node` or `-r slave`.

Common situations: Copy-pasted startup scripts from older SeaTunnel versions that used different role names, typos like `workes`, or custom orchestration scripts passing an unsupported role.

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

• Cluster name is required. Please specify it using -cn or --c
• cluster: %s is not running, Please start the cluster first.
• Failed to get cluster members information
• deploy mode not support : ${MODE}
• Failed to open AmazonDocumentDB source reader for database [

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