apache/seatunnel · error · IllegalArgumentException

restoreSourceJobId is required when restoreMode=${restoreMod

Error message

restoreSourceJobId is required when restoreMode=${restoreMode}

What it means

When restoreMode is set to a restoring value (e.g. FULL or LATE — anything whose isRestore() is true), the REST API must know which previous job's state to restore from, supplied via restoreSourceJobId. validateCheckpointRestoreRequest throws this IllegalArgumentException when restoreMode requests a restore but restoreSourceJobId is absent.

Source

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

                            validateCheckpointRestoreRequest(requestParams);
                            SeaTunnelServer seaTunnelServer = getSeaTunnelServer(false);
                            Config decryptConfig = ConfigShadeUtils.decryptConfig(tuple._2);
                            return submitJobInternal(
                                    decryptConfig,
                                    requestParams,
                                    seaTunnelServer,
                                    nodeEngine.getNode());
                        })
                .collect(JsonArray::new, JsonArray::add, JsonArray::add);
    }

    private void validateCheckpointRestoreRequest(Map<String, String> requestParams) {
        String restoreModeValue = requestParams.get(RestConstant.RESTORE_MODE);
        RestoreMode restoreMode =
                restoreModeValue == null ? RestoreMode.NONE : RestoreMode.valueOf(restoreModeValue);
        if (restoreMode.isRestore()
                && requestParams.get(RestConstant.RESTORE_SOURCE_JOB_ID) == null) {
            throw new IllegalArgumentException(
                    "restoreSourceJobId is required when restoreMode=" + restoreMode);
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Add restoreSourceJobId=<id of the job whose savepoint/state to restore> to the request.
Keep restoreMode unset (or NONE) if no state restore is desired.
Fetch the finished/failed job's id via the REST finished-jobs endpoint before resubmitting.

Example fix

// before
curl -X POST 'http://host:8080/submit-job?jobName=demo&restoreMode=FULL' --data @job.conf
// after
curl -X POST 'http://host:8080/submit-job?jobName=demo&restoreMode=FULL&restoreSourceJobId=861119875632570369' --data @job.conf

Defensive patterns

Strategy: validation

Validate before calling

const restoreMode = params.get("restoreMode") || "NONE";
const restoring = restoreMode === "FULL" || restoreMode === "LATE";
if (restoring && params.get("restoreSourceJobId") == null) {
  throw new Error("restoreMode=" + restoreMode + " requires restoreSourceJobId");
}

Try / catch

try { submit(params); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("restoreSourceJobId is required")) { /* fetch finished job id and resubmit */ } else throw e; }

Prevention

Record restoreSourceJobId together with restoreMode in your deployment scripts.
Distinguish jobId (new job) from restoreSourceJobId (state source) in tooling and docs.
Query the finished-jobs REST endpoint to resolve the source id before resubmitting.

When it happens

Trigger: POST to submit-job (single or batch path) with restoreMode=FULL (or another restore mode) while omitting the restoreSourceJobId parameter.

Common situations: Users enabling automatic state restore after a job failure but not recording the failed job's id; configs written with restoreMode set by a template that never injects restoreSourceJobId; confusion between jobId (target job) and restoreSourceJobId (source job) parameters.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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