{"record":{"id":"18a962c69fe5444a","repo":"apache/seatunnel","slug":"restoresourcejobid-is-required-when-restoremode-s","errorCode":null,"errorMessage":"restoreSourceJobId is required when restoreMode=%s","messagePattern":"restoreSourceJobId is required when restoreMode=(.+?)","errorType":"exception","errorClass":"JobException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/CheckpointRestoreValidator.java","lineNumber":42,"sourceCode":"\nimport java.util.function.LongFunction;\n\nfinal class CheckpointRestoreValidator {\n\n    private CheckpointRestoreValidator() {}\n\n    static void validate(\n            JobImmutableInformation jobImmutableInformation,\n            long destinationJobId,\n            LongFunction<JobStatus> activeSourceJobStatusResolver) {\n        if (jobImmutableInformation == null\n                || jobImmutableInformation.getRestoreMode() != RestoreMode.CHECKPOINT) {\n            return;\n        }\n\n        Long restoreSourceJobId = jobImmutableInformation.getRestoreSourceJobId();\n        if (restoreSourceJobId == null) {\n            throw new JobException(\n                    \"restoreSourceJobId is required when restoreMode=\"\n                            + jobImmutableInformation.getRestoreMode());\n        }\n        if (restoreSourceJobId == destinationJobId) {\n            throw new JobException(\n                    \"restoreSourceJobId must reference a historical terminal source job when restoreMode=CHECKPOINT\");\n        }\n\n        JobStatus sourceJobStatus =\n                activeSourceJobStatusResolver == null\n                        ? null\n                        : activeSourceJobStatusResolver.apply(restoreSourceJobId);\n        if (sourceJobStatus != null && !sourceJobStatus.isEndState()) {\n            throw new JobException(\n                    String.format(\n                            \"checkpoint restore requires a terminal source job, restoreSourceJobId=%s, current source job status=%s\",\n                            restoreSourceJobId, sourceJobStatus));\n        }","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/CheckpointRestoreValidator.java#L24-L60","documentation":"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.","triggerScenarios":"Submitting a job (validate on the master node) with jobImmutableInformation.restoreMode == RestoreMode.CHECKPOINT and getRestoreSourceJobId() == null.","commonSituations":"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.","solutions":["Pass the source job id when submitting, e.g. sh bin/seatunnel.sh --restore <sourceJobId> ...","Set restoreSourceJobId programmatically on the job submission request.","If no checkpoint restore is intended, submit with the default (no restore) mode instead of restoreMode=CHECKPOINT."],"exampleFix":"// before\nbin/seatunnel.sh --config job.conf -e run --restore-mode CHECKPOINT\n// after\nbin/seatunnel.sh --config job.conf -e run --restore-mode CHECKPOINT --restore-source-job-id 883745192014848","handlingStrategy":"validation","validationCode":"if (restoreMode == RestoreMode.CHECKPOINT && restoreSourceJobId == null) {\n  throw new IllegalArgumentException(\"--restore-source-job-id is required with --restore-mode CHECKPOINT\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  client.submitJob(request);\n} catch (JobException e) {\n  if (e.getMessage().startsWith(\"restoreSourceJobId is required\")) {\n    // resubmit with the source job id\n  }\n}","preventionTips":["Wrap restore submissions in a script that asserts the source id argument exists","Record source job ids from every finished job for later restores","Use client CLI flags rather than hand-built requests to avoid missing fields"],"tags":["checkpoint-restore","job-submission","missing-argument","zeta-engine"],"backgroundTag":"missing-required-argument","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}