apache/seatunnel · error · JobException

checkpoint restore requires a terminal source job, restoreSo

Error message

checkpoint restore requires a terminal source job, restoreSourceJobId=%s, current source job status=%s

What it means

When restoreMode=CHECKPOINT and a status resolver is available for the restore source job, the source job must be in an end state (finished/failed/canceled) because its final checkpoint data is what gets restored. If the source job is still running (or in a non-terminal state), validation throws this JobException.

Source

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

        }

        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. Wait until the source job reaches a terminal state (FINISHED/FAILED/CANCELED) before submitting the restore.
2. Verify restoreSourceJobId points at the completed job whose checkpoints you want.
3. Check the source job's status via REST API / seatunnel.sh client before resubmitting.
4. Fix automation to trigger restore only after source-job completion event.

Example fix

// before: restore while source still running
submitRestore(883745192014848L); // status = RUNNING
// after: poll until terminal state
while (!status(jobId).isEndState()) Thread.sleep(5000);
submitRestore(883745192014848L);

JobStatus s = getJobStatus(restoreSourceJobId); // via REST or client
if (s != null && !s.isEndState()) {
  throw new IllegalStateException("Wait for source job to finish before restoring: " + s);
}

try {
  client.submitJob(request);
} catch (JobException e) {
  if (e.getMessage().startsWith("checkpoint restore requires a terminal source job")) {
    // poll source status, resubmit after it ends
  }
}

When it happens

Trigger: validate() resolves activeSourceJobStatusResolver.apply(restoreSourceJobId) and the returned JobStatus.isEndState() is false (e.g. RUNNING, CREATED) while submitting a CHECKPOINT-mode restore.

Common situations: Attempting to restore from a source job that is still running; racing automation that submits the restore before the source job finished; querying the wrong job id (an active unrelated job).

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• restoreSourceJobId is required when restoreMode=%s
• restoreSourceJobId must reference a historical terminal sour
• schema-change-after checkpoint is already completed, job id:
• ${CONNECTOR_JAR_HA_STORAGE_TYPE} must in [localfile, hdfs]
• Failed to call factoryIdentifier method.

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