{"record":{"id":"b1ae2f792ac8d4c3","repo":"apache/seatunnel","slug":"unsupported-restore-mode-for-checkpoint-loading","errorCode":null,"errorMessage":"Unsupported restore mode for checkpoint loading: ${restoreMode}","messagePattern":"Unsupported restore mode for checkpoint loading: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/rest/RestJobExecutionEnvironment.java","lineNumber":181,"sourceCode":"                seaTunnelServer.getSeaTunnelConfig().getEngineConfig().getMetadataConfig();\n        return new MultipleTableJobConfigParser(\n                seaTunnelJobConfig,\n                idGenerator,\n                jobConfig,\n                commonPluginJars,\n                restoreMode.isRestore(),\n                pipelineCheckpoints,\n                metaDataConfig);\n    }\n\n    private List<JobPipelineCheckpointData> loadPipelineCheckpointsFromMasterNode() {\n        if (seaTunnelServer.isMasterNode() && seaTunnelServer.getCheckpointService() != null) {\n            if (restoreMode.isRestore()) {\n                return seaTunnelServer\n                        .getCheckpointService()\n                        .getLatestCheckpointData(String.valueOf(restoreSourceJobId), restoreMode);\n            }\n            throw new IllegalStateException(\n                    \"Unsupported restore mode for checkpoint loading: \" + restoreMode);\n        }\n\n        try {\n            Object response =\n                    NodeEngineUtil.sendOperationToMasterNode(\n                                    nodeEngine,\n                                    new GetJobCheckpointOperation(restoreSourceJobId, restoreMode))\n                            .join();\n            if (response == null) {\n                return Collections.emptyList();\n            }\n            return (List<JobPipelineCheckpointData>)\n                    nodeEngine.getSerializationService().toObject(response);\n        } catch (Exception e) {\n            throw new IllegalStateException(\n                    \"Failed to get checkpoint data from master node, restoreSourceJobId=\"\n                            + restoreSourceJobId,","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/rest/RestJobExecutionEnvironment.java#L163-L199","documentation":"loadPipelineCheckpointsFromMasterNode on the master node requires a restore-capable restoreMode to fetch checkpoint data via CheckpointService.getLatestCheckpointData. If the master node is reached but restoreMode.isRestore() is false, the code path is inconsistent (loading checkpoints in a non-restore mode), so it throws IllegalStateException.","triggerScenarios":"Internal call path where checkpoint loading is requested while restoreMode is not SAVEPOINT/RESTORE (e.g. normal submission mistakenly routed into the checkpoint-loading branch).","commonSituations":"REST request mixing a non-restore mode with checkpoint-loading parameters; code/version mismatch between client that set restoreMode and server expectation; custom REST integrations passing invalid mode values.","solutions":["Submit restore jobs with restoreMode=SAVEPOINT (or a mode where isRestore() is true) and a valid restoreSourceJobId","Do not pass checkpoint/restore parameters for normal (non-restore) job submissions","Upgrade client and server to matching SeaTunnel versions to avoid mode-enum mismatches"],"exampleFix":"// before\nrestoreMode = NORMAL; loadCheckpoints()\n// after\nrestoreMode = SAVEPOINT; // with restoreSourceJobId set\nloadCheckpoints()","handlingStrategy":"validation","validationCode":"// only load checkpoints when mode is restore\nif (restoreMode == null || !restoreMode.isRestore()) { skipCheckpointLoad(); }","typeGuard":null,"tryCatchPattern":"try {\n    loadCheckpoints();\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Unsupported restore mode\")) {\n        // fix restoreMode before retrying\n    }\n}","preventionTips":["Only pass checkpoint-loading params in restore modes","Keep client/server SeaTunnel versions aligned","Use canonical restoreMode values (e.g. SAVEPOINT)"],"tags":["zeta-engine","rest-api","restore-mode"],"backgroundTag":"invalid-enum-value","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}