apache/seatunnel · error · IllegalArgumentException

--savepoint and --restore-with-checkpoint are mutually exclu

Error message

--savepoint and --restore-with-checkpoint are mutually exclusive

What it means

ClientCommandArgs.buildCommand rejects passing --savepoint together with --restore-with-checkpoint. Restoring with checkpoint semantics already involves savepoint state handling, so the combination is ambiguous and is rejected as IllegalArgumentException at argument-validation time.

Source

Thrown at seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/args/ClientCommandArgs.java:174

            names = {"--async"},
            description =
                    "Run the job asynchronously, when the job is submitted, the client will exit")
    private boolean async = false;

    @Parameter(
            names = {"-cj", "--close", "--close-job"},
            description = "Close client the task will also be closed")
    private boolean closeJob = true;

    @Override
    public Command<?> buildCommand() {
        validateCommandOptions();
        if (restoreJobId != null && restoreWithCheckpointJobId != null) {
            throw new IllegalArgumentException(
                    "--restore and --restore-with-checkpoint are mutually exclusive");
        }
        if (savePointJobId != null && restoreWithCheckpointJobId != null) {
            throw new IllegalArgumentException(
                    "--savepoint and --restore-with-checkpoint are mutually exclusive");
        }
        if (restoreWithCheckpointJobId != null) {
            restoreWithCheckpointJobId =
                    normalizeNumericJobId(
                            restoreWithCheckpointJobId,
                            "restoreSourceJobId is required when using --restore-with-checkpoint",
                            "--restore-with-checkpoint requires a numeric jobId, got: ");
        }
        if (customJobId != null) {
            customJobId =
                    normalizeNumericJobId(
                            customJobId,
                            "--set-job-id requires a non-blank jobId",
                            "--set-job-id requires a numeric jobId, got: ");
        }
        Common.setDeployMode(getDeployMode());
        if (dryRun == DryRun.SAMPLE) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Remove --savepoint when using --restore-with-checkpoint; they must run as separate commands
2. First run the savepoint/stop command, then submit a new job with --restore or --restore-with-checkpoint only
3. Audit wrapper scripts that combine job-stop and job-restore flags

Example fix

// before
--savepoint 12345 --restore-with-checkpoint 12345
// after
--restore-with-checkpoint 12345

if (cliArgs.contains("--savepoint") && cliArgs.stream().anyMatch(a -> a.startsWith("--restore-with-checkpoint"))) {
    throw new IllegalArgumentException("--savepoint cannot be combined with --restore-with-checkpoint");
}

try {
    client.submit(args);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("--savepoint and --restore-with-checkpoint")) {
        log.error("Run savepoint and restore as separate commands");
    }
}

When it happens

Trigger: Submitting a job with both --savepoint <jobId> (trigger savepoint/stop) and --restore-with-checkpoint <jobId> on the command line, or setting both fields on ClientCommandArgs before buildCommand().

Common situations: Scripts chaining a savepoint stop and a checkpoint-based restore in one invocation; misunderstanding --savepoint as an alternative restore source.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• SeaTunnel job on spark engine deploy mode only support these
• --restore and --restore-with-checkpoint are mutually exclusi
• --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/24304e803e2b1829. Report an issue: GitHub.