apache/seatunnel · error · JobException

restoreSourceJobId is required when restoreMode=%s

Error message

restoreSourceJobId is required when restoreMode=%s

What it means

CheckpointRestoreValidator.validate enforces that a job submitted with restoreMode=CHECKPOINT supplies restoreSourceJobId (the job whose checkpoint data will be restored). If it is null, job submission fails with this JobException before scheduling.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/CheckpointRestoreValidator.java:42

import java.util.function.LongFunction;

final class CheckpointRestoreValidator {

    private CheckpointRestoreValidator() {}

    static void validate(
            JobImmutableInformation jobImmutableInformation,
            long destinationJobId,
            LongFunction<JobStatus> activeSourceJobStatusResolver) {
        if (jobImmutableInformation == null
                || jobImmutableInformation.getRestoreMode() != RestoreMode.CHECKPOINT) {
            return;
        }

        Long restoreSourceJobId = jobImmutableInformation.getRestoreSourceJobId();
        if (restoreSourceJobId == null) {
            throw new JobException(
                    "restoreSourceJobId is required when restoreMode="
                            + jobImmutableInformation.getRestoreMode());
        }
        if (restoreSourceJobId == destinationJobId) {
            throw new JobException(
                    "restoreSourceJobId must reference a historical terminal source job when restoreMode=CHECKPOINT");
        }

        JobStatus sourceJobStatus =
                activeSourceJobStatusResolver == null
                        ? null
                        : activeSourceJobStatusResolver.apply(restoreSourceJobId);
        if (sourceJobStatus != null && !sourceJobStatus.isEndState()) {
            throw new JobException(
                    String.format(
                            "checkpoint restore requires a terminal source job, restoreSourceJobId=%s, current source job status=%s",
                            restoreSourceJobId, sourceJobStatus));
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Pass the source job id when submitting, e.g. sh bin/seatunnel.sh --restore <sourceJobId> ...
2. Set restoreSourceJobId programmatically on the job submission request.
3. If no checkpoint restore is intended, submit with the default (no restore) mode instead of restoreMode=CHECKPOINT.

Example fix

// before
bin/seatunnel.sh --config job.conf -e run --restore-mode CHECKPOINT
// after
bin/seatunnel.sh --config job.conf -e run --restore-mode CHECKPOINT --restore-source-job-id 883745192014848

if (restoreMode == RestoreMode.CHECKPOINT && restoreSourceJobId == null) {
  throw new IllegalArgumentException("--restore-source-job-id is required with --restore-mode CHECKPOINT");
}

try {
  client.submitJob(request);
} catch (JobException e) {
  if (e.getMessage().startsWith("restoreSourceJobId is required")) {
    // resubmit with the source job id
  }
}

When it happens

Trigger: Submitting a job (validate on the master node) with jobImmutableInformation.restoreMode == RestoreMode.CHECKPOINT and getRestoreSourceJobId() == null.

Common situations: Using --restore / checkpoint-restore restore mode without passing the source job id; building a custom submission client that sets restoreMode but forgets the restoreSourceJobId 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

• restoreSourceJobId must reference a historical terminal sour
• checkpoint restore requires a terminal source job, restoreSo
• The job id %s is waiting for terminal state cleanup, please
• The job id %s has already been submitted and is not starting
• Unsupported checkpoint history status %s

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