apache/seatunnel · error · CheckpointStorageException

No checkpoint found, job(${jobId}), pipeline(${pipelineId}),

Error message

No checkpoint found, job(${jobId}), pipeline(${pipelineId}), checkpoint(${checkpointId})

What it means

HdfsStorage.getCheckpoint throws CheckpointStorageException when it cannot locate a checkpoint file matching the given jobId, pipelineId and checkpointId in the HDFS storage directory. The storage walks the job directory, tries to read matching files, and if nothing matches (or reading fails per-file) it falls through to this final throw. It signals the requested checkpoint simply does not exist in storage.

Source

Thrown at seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-hdfs/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/hdfs/HdfsStorage.java:270

            log.info("No checkpoint found for this job,  the job id is: " + jobId);
            return null;
        }
        for (String fileName : fileNames) {
            if (pipelineId.equals(getPipelineIdByFileName(fileName))
                    && checkpointId.equals(getCheckpointIdByFileName(fileName))) {
                try {
                    return readPipelineState(fileName, jobId);
                } catch (Exception e) {
                    log.error(
                            "Failed to get checkpoint {} for job {}, pipeline {}",
                            checkpointId,
                            jobId,
                            pipelineId,
                            e);
                }
            }
        }
        throw new CheckpointStorageException(
                String.format(
                        "No checkpoint found, job(%s), pipeline(%s), checkpoint(%s)",
                        jobId, pipelineId, checkpointId));
    }

    @Override
    public synchronized void deleteCheckpoint(String jobId, String pipelineId, String checkpointId)
            throws CheckpointStorageException {
        String path = getStorageParentDirectory() + jobId;
        List<String> fileNames = getFileNames(path);
        if (fileNames.isEmpty()) {
            throw new CheckpointStorageException(
                    "No checkpoint found for job, job id is: " + jobId);
        }
        fileNames.forEach(
                fileName -> {
                    if (pipelineId.equals(getPipelineIdByFileName(fileName))
                            && checkpointId.equals(getCheckpointIdByFileName(fileName))) {

View on GitHub (pinned to cf67b549a7)

Solutions

Verify the jobId/pipelineId/checkpointId triple exists by listing files under the storage parent directory + jobId.
Confirm the storage directory configuration (storage parent path) points at the cluster where the job actually ran.
Re-run the job or fall back to getLatestCheckpoint if you need the most recent checkpoint rather than an exact one.
Handle CheckpointStorageException in the caller and treat it as 'not found' rather than retrying.

Example fix

// before
CheckpointData data = storage.getCheckpoint(jobId, pipelineId, unknownCheckpointId);
// after
CheckpointData data;
try {
    data = storage.getCheckpoint(jobId, pipelineId, unknownCheckpointId);
} catch (CheckpointStorageException e) {
    data = storage.getLatestCheckpoint(jobId, pipelineId);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Check the checkpoint file exists before reading
List<String> names = java.util.Arrays.asList(
    new org.apache.hadoop.fs.Path(parentDir + jobId).getFileSystem(conf)
        .listStatus(new org.apache.hadoop.fs.Path(parentDir + jobId))
).stream().map(s -> s.getPath().getName())
 .filter(n -> n.contains(pipelineId) && n.contains(checkpointId))
 .collect(java.util.stream.Collectors.toList());
boolean exists = !names.isEmpty();

Type guard

boolean checkpointExists(String jobId, String pipelineId, String checkpointId) {
    try { storage.getCheckpoint(jobId, pipelineId, checkpointId); return true; }
    catch (CheckpointStorageException e) { return false; }
}

Try / catch

try {
    CheckpointData cp = storage.getCheckpoint(jobId, pipelineId, checkpointId);
} catch (CheckpointStorageException e) {
    if (e.getMessage().startsWith("No checkpoint found")) {
        // treat as not-found: use latest checkpoint or fail job recovery explicitly
    } else { throw e; }
}

Prevention

Derive checkpoint IDs from stored metadata rather than hardcoding or reconstructing them.
Use getLatestCheckpoint when any recent checkpoint is acceptable instead of an exact ID.
Confirm the storage parent directory config matches the cluster where the job ran.
Account for checkpoint retention/cleanup deleting files before you query them.

When it happens

Trigger: Calling getCheckpoint(jobId, pipelineId, checkpointId) with an ID combination that has no corresponding checkpoint file in the job's HDFS directory, e.g. asking for an already-deleted checkpoint or a typo'd checkpointId.

Common situations: Querying a checkpoint after job cleanup/retention deleted it; stale job metadata referencing purged checkpoints; cluster misconfiguration pointing at the wrong storage directory; checkpoint never completed so the file was never written.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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