apache/seatunnel · error · IllegalArgumentException

restoreSourceJobId is required when restoreMode=CHECKPOINT

Error message

restoreSourceJobId is required when restoreMode=CHECKPOINT

What it means

SeaTunnelClient.restoreFromCheckpointExecutionContext validates that sourceJobId (the original job whose checkpoint is being restored) is non-null when restoreMode=CHECKPOINT. Without it the engine cannot locate the checkpoint of the source job, so it fails fast with IllegalArgumentException.

Solutions

1. Pass the original job's id via restoreSourceJobId in the submission request or the client CLI flag.
2. If a plain run was intended, remove the restoreMode=CHECKPOINT options.
3. When calling the constructor path programmatically, supply a non-null Long sourceJobId.
4. Upgrade client and engine together if one side predates the restore API.

Example fix

// before
client.createExecutionEnvironment(filePath, variables, jobConfig, seaTunnelConfig, null, jobId);
// after
client.createExecutionEnvironment(filePath, variables, jobConfig, seaTunnelConfig, sourceJobId, jobId);

if (restoreMode == RestoreMode.CHECKPOINT && (sourceJobId == null || sourceJobId <= 0)) {
    throw new IllegalArgumentException("restoreSourceJobId is required for CHECKPOINT restore");
}

try {
    return client.createExecutionEnvironment(filePath, variables, jobConfig, cfg, sourceJobId, jobId);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("restoreSourceJobId")) {
        throw new ConfigurationException("Supply restoreSourceJobId for CHECKPOINT restore", e);
    }
    throw e;
}

When it happens

Trigger: Calling the CHECKPOINT-mode restore path (createExecutionEnvironment with restoreMode=CHECKPOINT) while passing null for sourceJobId.

Common situations: Developer enables checkpoint restore but forgets to supply restoreSourceJobId in the submission request or CLI flags; copied snippet drops the restore parameter; older client versions that do not send the id.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• JsonPath array cannot be null or empty
• Unsupported config type, configKey
• accessId and accesskey must be provided when sts_token is…
• Agent config is not a readable file
• agent.id must be non-empty after resolution.

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

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-client/src/main/java/org/apache/seatunnel/engine/client/SeaTunnelClient.java:126

                filePath,
                variables,
                hazelcastClient,
                seaTunnelConfig,
                RestoreMode.SAVEPOINT,
                jobId,
                jobId);
    }

    @Override
    public ClientJobExecutionEnvironment restoreFromCheckpointExecutionContext(
            @NonNull String filePath,
            List<String> variables,
            @NonNull JobConfig jobConfig,
            @NonNull SeaTunnelConfig seaTunnelConfig,
            @NonNull Long sourceJobId,
            Long jobId) {
        if (sourceJobId == null) {
            throw new IllegalArgumentException(
                    "restoreSourceJobId is required when restoreMode=CHECKPOINT");
        }
        return new ClientJobExecutionEnvironment(
                jobConfig,
                filePath,
                variables,
                hazelcastClient,
                seaTunnelConfig,
                RestoreMode.CHECKPOINT,
                sourceJobId,
                jobId);
    }

    @Override
    public JobClient createJobClient() {
        return new JobClient(hazelcastClient);
    }

View on GitHub (pinned to cf67b549a7)