apache/seatunnel · error · SeaTunnelEngineException

Cluster name is required. Please specify it using -cn or --c

Error message

Cluster name is required. Please specify it using -cn or --cluster option.

What it means

The `-m` / members command connects to a running SeaTunnel cluster as a Hazelcast client and needs to know which cluster to join. showClusterMembers throws SeaTunnelEngineException when no cluster name was provided via `-cn`/`--cluster`, because connecting without an explicit name could hit the wrong cluster. It fails before any network attempt is made.

Source

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

                if (m.matches()) {
                    return Integer.parseInt(m.group(3)) == 0 && Integer.parseInt(m.group(4)) < 102;
                }
                return true;
            } catch (Exception e) {
                return true;
            }
        } else {
            return !SystemUtils.isJavaVersionAtLeast(JavaVersion.JAVA_1_8);
        }
    }

    @VisibleForTesting
    public Set<Member> showClusterMembers() {
        HazelcastClientInstanceImpl client = null;
        try {
            String clusterName = serverCommandArgs.getClusterName();
            if (StringUtils.isBlank(clusterName)) {
                throw new SeaTunnelEngineException(
                        "Cluster name is required. Please specify it using -cn or --cluster option.");
            }
            ClientConfig clientConfig = ConfigProvider.locateAndGetClientConfig();
            clientConfig.setClusterName(clusterName);
            client =
                    ((HazelcastClientProxy) HazelcastClient.newHazelcastClient(clientConfig))
                            .client;
            if (!client.getLifecycleService().isRunning()) {
                throw new SeaTunnelEngineException(
                        String.format(
                                "cluster: %s is not running, Please start the cluster first.",
                                clusterName));
            }
            Set<Member> members = client.getCluster().getMembers();
            if (members.isEmpty()) {
                System.out.println("No active members found in the cluster.");
                return members;
            }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Pass the cluster name: `seatunnel-cluster.sh -m -cn <clusterName>`
2. Use the same `-cn` value the cluster was started with (default is seatunnel-cluster if unset)
3. Set the cluster name in the Hazelcast client config if scripting the call
4. Check the running cluster's JVM args or seatunnel.yaml to confirm its cluster name

Example fix

// before
sh bin/seatunnel-cluster.sh -m
// after
sh bin/seatunnel-cluster.sh -m -cn seatunnel-cluster

if (args.getClusterName() == null || args.getClusterName().isBlank()) {
    throw new IllegalArgumentException("Pass -cn <clusterName> to the members command");
}

try {
    Set<Member> members = command.showClusterMembers();
} catch (SeaTunnelEngineException e) {
    if (e.getMessage().contains("Cluster name is required")) {
        log.error("Re-run with -cn <clusterName>");
    }
}

When it happens

Trigger: Running `seatunnel-cluster.sh -m` (members) without `-cn <name>`/`--cluster <name>` while serverCommandArgs.getClusterName() returns blank.

Common situations: Operators running the members command against a cluster that was started with a custom -cn value but forgetting to pass the same name to the client command; multi-cluster environments where defaults are not safe.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• cluster: %s is not running, Please start the cluster first.
• Failed to get cluster members information
• Not supported cluster role: ${clusterRole}
• cluster have no master node
• Node heartbeat timeout, disconnected for resource manager. N

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