apache/seatunnel · error · CheckpointStorageException

Failed to read checkpoint data, file name is ${fileName},job

Error message

Failed to read checkpoint data, file name is ${fileName},job id is ${jobId}

What it means

readPipelineState opens a checkpoint file on HDFS via FSDataInputStream, copies bytes, and deserializes it; an IOException anywhere in that sequence is wrapped into CheckpointStorageException naming the file and job. Callers (getCheckpoint, getLatestCheckpoint, getAllCheckpoints, etc.) surface this when a checkpoint file exists but cannot be read or deserialized.

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:370

    }

    /**
     * Get checkpoint name
     *
     * @param fileName file name
     * @return checkpoint data
     */
    private PipelineState readPipelineState(String fileName, String jobId)
            throws CheckpointStorageException {
        fileName =
                getStorageParentDirectory() + jobId + DEFAULT_CHECKPOINT_FILE_PATH_SPLIT + fileName;
        try (FSDataInputStream in = fs.open(new Path(fileName));
                ByteArrayOutputStream stream = new ByteArrayOutputStream()) {
            IOUtils.copyBytes(in, stream, 1024);
            byte[] bytes = stream.toByteArray();
            return deserializeCheckPointData(bytes);
        } catch (IOException e) {
            throw new CheckpointStorageException(
                    String.format(
                            "Failed to read checkpoint data, file name is %s,job id is %s",
                            fileName, jobId),
                    e);
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the file exists and is readable on HDFS and re-run the read; transient block/network failures often clear.
2. Check for corruption by inspecting the file (hdfs fsck) and re-run the job if the checkpoint is unrecoverable.
3. Ensure the seatunnel-engine version writing the checkpoint matches the one reading it (serialization compatibility).
4. Retry the read with backoff for transient IOExceptions from HDFS.

Example fix

// before
CheckpointData cp = storage.getCheckpoint(jobId, pipelineId, checkpointId);
// after
CheckpointData cp;
try {
    cp = storage.getCheckpoint(jobId, pipelineId, checkpointId);
} catch (CheckpointStorageException e) {
    if (e.getMessage().startsWith("Failed to read checkpoint data")) {
        cp = storage.getLatestCheckpoint(jobId, pipelineId); // fall back to an intact checkpoint
    } else throw e;
}

try {
    CheckpointData cp = storage.getCheckpoint(jobId, pipelineId, checkpointId);
} catch (CheckpointStorageException e) {
    if (e.getMessage().startsWith("Failed to read checkpoint data")) {
        // transient HDFS I/O or corrupt file: retry, then fall back to another checkpoint
    } else { throw e; }
}

When it happens

Trigger: Calling any checkpoint-read API when the target file was deleted mid-read, HDFS is unavailable, block read fails, or the byte content cannot be deserialized as checkpoint data (corrupt/truncated file).

Common situations: Corrupted checkpoint files after abrupt cluster shutdown; file deleted between listing and reading (race with cleanup); HDFS under-replicated/unavailable blocks; version mismatch where old serialized data cannot be deserialized by a newer build.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to delete checkpoint for job {}
• FILE_LIST_GET_FAILED
• Failed during target_bulk_listing for path=%s
• Checking catalog path %s exists exception.
• No checkpoint found, job(${jobId}), pipeline(${pipelineId}),

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