apache/seatunnel · critical · IllegalStateException

Checkpoint is enabled and job starts with savepoint, but…

Error message

Checkpoint is enabled and job starts with savepoint, but checkpoint storage is not available

What it means

JobMaster.resolveCheckpointStorageOrFallback validates checkpoint configuration at job initialization. If checkpointing is enabled AND the job is starting from a savepoint (restore job or restart), but no checkpoint storage (IMap state) is available, the job cannot recover and an IllegalStateException is thrown. Checkpoint storage is essential to read the savepoint state from which the job resumes.

Solutions

1. Restore the checkpoint storage/state (IMap persistence or checkpoint directory) that the savepoint references.
2. Submit the job without the savepoint (fresh start) if recovery from this savepoint is impossible.
3. Disable checkpointing for the job if a savepoint start is not actually required.
4. Verify the checkpoint storage configuration (storage plugin) points to accessible, existing storage.

Example fix

// before: resume with missing savepoint
sh bin/seatunnel.sh -c job.conf -r <jobId>
// after: start fresh since savepoint state is gone
sh bin/seatunnel.sh -c job.conf

// before resuming
boolean storageExists = checkpointStoragePathExists(savepointPath);
boolean willStartWithSavepoint = isRestoreJob || restart;
if (willStartWithSavepoint && !storageExists) {
    throw new IllegalStateException("checkpoint storage missing; cannot resume from savepoint");
}

try {
    resumeJob(jobId);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("checkpoint storage is not available")) {
        submitFreshJob(jobConf); // fall back to a fresh start
    } else throw e;
}

When it happens

Trigger: Submitting/restarting a job with checkpoint enabled and a savepoint path (isRestoreJob() true or restart=true) while the checkpoint storage IMap/locally-resolved storage is unavailable - e.g. resuming a job whose checkpoint state was deleted, or running in an environment where the storage was never initialized.

Common situations: Restoring a job from a savepoint after the cluster's checkpoint storage was wiped; restarting a job after IMap data loss (cluster restarted without persistence); running local examples where the checkpoint directory/state was manually removed.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• The job with id ' ' save point failed
• ACKNOWLEDGE_FAILED
• ACKNOWLEDGE_FAILED
• Cannot fetch from another split - no split remaining.
• checkpoint do not exist or have already been committed.

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

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/master/JobMaster.java:371

    }

    private CheckpointStorage resolveCheckpointStorageOrFallback(boolean restart) {
        if (seaTunnelServer != null && seaTunnelServer.getCheckpointService() != null) {
            CheckpointStorage storage =
                    seaTunnelServer.getCheckpointService().getCheckpointStorage();
            if (storage != null) {
                return storage;
            }
        }

        boolean checkpointEnabled =
                jobCheckpointConfig != null && jobCheckpointConfig.isCheckpointEnable();
        boolean startWithSavePoint =
                jobImmutableInformation != null
                        && (jobImmutableInformation.isRestoreJob() || restart);

        if (checkpointEnabled && startWithSavePoint) {
            throw new IllegalStateException(
                    "Checkpoint is enabled and job starts with savepoint, but checkpoint storage is not available");
        }

        // When checkpoint is disabled, CheckpointManager will not touch the storage. We still need
        // a non-null placeholder to avoid NPEs during job initialization (especially in local
        // example runs where SeaTunnelServer components may initialize asynchronously).
        return new UnsupportedCheckpointStorage();
    }

    private static final class UnsupportedCheckpointStorage implements CheckpointStorage {
        private static UnsupportedOperationException unavailable() {
            return new UnsupportedOperationException("Checkpoint storage is unavailable");
        }

        @Override
        public String storeCheckPoint(PipelineState state) {
            throw unavailable();
        }

View on GitHub (pinned to cf67b549a7)