apache/seatunnel · error · IllegalStateException

Unsupported restore mode for checkpoint loading: ${restoreMo

Error message

Unsupported restore mode for checkpoint loading: ${restoreMode}

What it means

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.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/rest/RestJobExecutionEnvironment.java:181

                seaTunnelServer.getSeaTunnelConfig().getEngineConfig().getMetadataConfig();
        return new MultipleTableJobConfigParser(
                seaTunnelJobConfig,
                idGenerator,
                jobConfig,
                commonPluginJars,
                restoreMode.isRestore(),
                pipelineCheckpoints,
                metaDataConfig);
    }

    private List<JobPipelineCheckpointData> loadPipelineCheckpointsFromMasterNode() {
        if (seaTunnelServer.isMasterNode() && seaTunnelServer.getCheckpointService() != null) {
            if (restoreMode.isRestore()) {
                return seaTunnelServer
                        .getCheckpointService()
                        .getLatestCheckpointData(String.valueOf(restoreSourceJobId), restoreMode);
            }
            throw new IllegalStateException(
                    "Unsupported restore mode for checkpoint loading: " + restoreMode);
        }

        try {
            Object response =
                    NodeEngineUtil.sendOperationToMasterNode(
                                    nodeEngine,
                                    new GetJobCheckpointOperation(restoreSourceJobId, restoreMode))
                            .join();
            if (response == null) {
                return Collections.emptyList();
            }
            return (List<JobPipelineCheckpointData>)
                    nodeEngine.getSerializationService().toObject(response);
        } catch (Exception e) {
            throw new IllegalStateException(
                    "Failed to get checkpoint data from master node, restoreSourceJobId="
                            + restoreSourceJobId,

View on GitHub (pinned to cf67b549a7)

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

Example fix

// before
restoreMode = NORMAL; loadCheckpoints()
// after
restoreMode = SAVEPOINT; // with restoreSourceJobId set
loadCheckpoints()

Defensive patterns

Strategy: validation

Validate before calling

// only load checkpoints when mode is restore
if (restoreMode == null || !restoreMode.isRestore()) { skipCheckpointLoad(); }

Try / catch

try {
    loadCheckpoints();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unsupported restore mode")) {
        // fix restoreMode before retrying
    }
}

Prevention

Only pass checkpoint-loading params in restore modes
Keep client/server SeaTunnel versions aligned
Use canonical restoreMode values (e.g. SAVEPOINT)

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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