apache/seatunnel · error · IllegalArgumentException

restoreSourceJobId is required when restoreMode=${restoreMod

Error message

restoreSourceJobId is required when restoreMode=${restoreMode}

What it means

For SAVEPOINT restore mode submissions via REST, a restoreSourceJobId is mandatory. Legacy contract: if absent but jobId is present, jobId is reused as the restore source; if neither exists, IllegalArgumentException is thrown explaining that restoreSourceJobId is required for the given restoreMode.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/rest/service/BaseService.java:1341

        JobConfig jobConfig = new JobConfig();
        jobConfig.setName(
                StringUtils.isEmpty(requestParams.get(RestConstant.JOB_NAME))
                        ? jobName
                        : requestParams.get(RestConstant.JOB_NAME));

        RestoreMode restoreMode = resolveRestoreMode(requestParams);
        String jobIdStr = requestParams.get(RestConstant.JOB_ID);
        Long finalJobId = StringUtils.isNotBlank(jobIdStr) ? Long.parseLong(jobIdStr) : null;
        Long restoreSourceJobId =
                StringUtils.isNotBlank(requestParams.get(RestConstant.RESTORE_SOURCE_JOB_ID))
                        ? Long.parseLong(requestParams.get(RestConstant.RESTORE_SOURCE_JOB_ID))
                        : null;
        // Keep the legacy savepoint REST contract where jobId also identifies the restore source.
        if (restoreMode == RestoreMode.SAVEPOINT && restoreSourceJobId == null) {
            if (finalJobId != null) {
                restoreSourceJobId = finalJobId;
            } else {
                throw new IllegalArgumentException(
                        "restoreSourceJobId is required when restoreMode=" + restoreMode);
            }
        }
        RestJobExecutionEnvironment restJobExecutionEnvironment =
                new RestJobExecutionEnvironment(
                        seaTunnelServer,
                        jobConfig,
                        config,
                        node,
                        restoreMode,
                        restoreSourceJobId,
                        finalJobId);
        JobImmutableInformation jobImmutableInformation = restJobExecutionEnvironment.build();
        long jobId = jobImmutableInformation.getJobId();
        if (!seaTunnelServer.isMasterNode()) {

            NodeEngineUtil.sendOperationToMasterNode(
                            node.nodeEngine,

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add restoreSourceJobId to the request pointing at the job whose savepoint you restore from
2. Alternatively pass jobId with the source job's id (legacy savepoint behavior)
3. Verify restoreMode value is intentional; use non-restore mode if you do not want savepoint restore

Example fix

// before
{"restoreMode":"SAVEPOINT"}
// after
{"restoreMode":"SAVEPOINT","restoreSourceJobId":"863300353636515841"}

if (restoreMode === 'SAVEPOINT' && !restoreSourceJobId && !jobId) throw new Error('restoreSourceJobId (or jobId) required for SAVEPOINT restore');

try {
    await post('/submit-job', payload);
} catch (e) {
    if (String(e).includes('restoreSourceJobId is required')) {
        // add restoreSourceJobId and resend
    }
}

When it happens

Trigger: Submitting with restoreMode=SAVEPOINT while both restoreSourceJobId and jobId are missing/null in the request.

Common situations: Starting a job from a savepoint but forgetting to reference the source job; migrating jobs across clusters without carrying the original jobId; client SDK not mapping the field.

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

• Please provide jobId when start with save point.
• --savepoint and --restore-with-checkpoint are mutually exclu
• No checkpoint found for jobId=${jobId}, restoreMode=${restor
• Request body is empty.
• Invalid JSON format in request body.

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