apache/seatunnel · error · SavePointFailedException

The job with id '%s' save point failed

Error message

The job with id '%s' save point failed

What it means

This error is thrown on the stop-with-savepoint path when JobMaster.savePoint() completes with false, meaning the savepoint checkpoint did not succeed. The asynchronous supplyAsync block raises SavePointFailedException with this message, failing the caller's future. The job may still be running; only the savepoint attempt failed.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/CoordinatorService.java:1523

        return state instanceof JobStatus ? (JobStatus) state : null;
    }

    public PassiveCompletableFuture<Void> savePoint(long jobId) {
        CompletableFuture<Void> voidCompletableFuture = new CompletableFuture<>();
        if (!runningJobMasterMap.containsKey(jobId)) {
            SavePointFailedException exception =
                    new SavePointFailedException(
                            "The job with id '" + jobId + "' not running, save point failed");
            logger.warning(exception);
            voidCompletableFuture.completeExceptionally(exception);
        } else {
            voidCompletableFuture =
                    new PassiveCompletableFuture<>(
                            CompletableFuture.supplyAsync(
                                    () -> {
                                        JobMaster runningJobMaster = runningJobMasterMap.get(jobId);
                                        if (!runningJobMaster.savePoint().join()) {
                                            throw new SavePointFailedException(
                                                    "The job with id '"
                                                            + jobId
                                                            + "' save point failed");
                                        }
                                        try {
                                            waitForJobComplete(jobId).get();
                                        } catch (Throwable e) {
                                            logger.warning(
                                                    String.format(
                                                            "The job with id '%s' waiting state complete failed",
                                                            jobId));
                                        }
                                        return null;
                                    },
                                    executorService));
        }
        return new PassiveCompletableFuture<>(voidCompletableFuture);
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Retry the savepoint request; transient checkpoint failures often succeed on a second attempt.
2. Increase checkpoint timeout / interval and reduce checkpoint pressure (smaller state, more resources).
3. Verify checkpoint storage connectivity and write permissions from all cluster nodes.
4. Check JobMaster/checkpoint logs for the underlying checkpoint failure cause before retrying.

Example fix

// before: checkpoint config prone to timeout
checkpoint.interval=1000
checkpoint.timeout=30000
// after: larger timeout for big state
checkpoint.interval=60000
checkpoint.timeout=300000
// then retry the API call
jobClient.savePoint(jobId).get(5, TimeUnit.MINUTES);

// check the job is running before requesting a savepoint
JobResult r = jobClient.getJobDetail(jobId);
if (r == null || r.getJobStatus() != JobStatus.RUNNING) {
    throw new IllegalStateException("job not running; savepoint would fail");
}

try {
    jobClient.savePoint(jobId).get(5, TimeUnit.MINUTES);
} catch (Exception e) {
    if (e.getMessage() != null && e.getMessage().contains("save point failed")) {
        jobClient.savePoint(jobId).get(5, TimeUnit.MINUTES); // one retry
    } else { throw e; }
}

When it happens

Trigger: Calling CoordinatorService.savePoint(jobId) when the triggered checkpoint fails or times out, so runningJobMaster.savePoint().join() returns false.

Common situations: Heavy backpressure or large state exceeding the checkpoint timeout; unreachable or slow checkpoint storage (HDFS/S3/OSS); savepoint requested while the job master is restarting or missing.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Unknown checkpoint type:
• Failed to load readyToCloseStartingTask from IMap, key: %s
• Failed to persist readyToCloseStartingTask to IMap, key: %s
• Unsupported close starting task
• schema-change-after checkpoint is already completed, job id:

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