apache/seatunnel · error · CheckpointStorageException

Failed to write checkpoint data to file ${fileName}

Error message

Failed to write checkpoint data to file ${fileName}

What it means

After successfully creating the checkpoint file, LocalFileStorage.storeCheckPoint writes the serialized bytes with FileUtils.writeByteArrayToFile; an IOException here is wrapped as 'Failed to write checkpoint data to file <fileName>'. The file exists but its content could not be written, leaving a likely empty or partial checkpoint file.

Source

Thrown at seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-local-file/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/localfile/LocalFileStorage.java:108

        }
        // Consider file paths for different operating systems
        String fileName =
                getStorageParentDirectory()
                        + state.getJobId()
                        + File.separator
                        + getCheckPointName(state);

        File file = new File(fileName);
        try {
            FileUtils.touch(file);
        } catch (IOException e) {
            throw new CheckpointStorageException("Failed to create checkpoint file " + fileName, e);
        }

        try {
            FileUtils.writeByteArrayToFile(file, datas);
        } catch (IOException e) {
            throw new CheckpointStorageException(
                    "Failed to write checkpoint data to file " + fileName, e);
        }

        return fileName;
    }

    @Override
    public List<PipelineState> getAllCheckpoints(String jobId) throws CheckpointStorageException {
        File filePath = new File(getStorageParentDirectory() + jobId);
        if (!filePath.exists()) {
            return new ArrayList<>();
        }

        Collection<File> fileList;
        try {
            fileList = FileUtils.listFiles(filePath, FILE_EXTENSIONS, true);
        } catch (Exception e) {
            throw new CheckpointStorageException(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Free disk space / check df -h on the storage volume, then re-run the job (checkpointing will retry on the next trigger).
2. Check filesystem health (dmesg, mount options) and ensure it is writable.
3. Remove the leftover empty/partial checkpoint file before retrying so stale files don't confuse readers.
4. Exclude the storage directory from aggressive cleanup scripts that could delete files mid-write.

Example fix

// before
$ df -h /data/seatunnel
/dev/sda1  100G  100G  0  100% /data
// after
$ df -h /data/seatunnel
/dev/sda1  100G   62G   38G  62% /data  # checkpoint write succeeds

java.io.File dir = new java.io.File(storageParentDir);
long usable = dir.getUsableSpace();
if (usable < 512L * 1024 * 1024)
    throw new IllegalStateException("Low disk space on checkpoint storage: " + usable + " bytes free");

try {
    storage.storeCheckPoint(state);
} catch (CheckpointStorageException e) {
    if (e.getMessage().startsWith("Failed to write checkpoint data to file")) {
        // likely disk-full/IO error: free space or check volume health, then retry
    }
    throw e;
}

When it happens

Trigger: storeCheckPoint called when the disk fills up between file creation and write, the filesystem goes read-only, I/O errors occur (bad disk), or another process holds conflicting access on the file.

Common situations: Disk-full conditions on the node running the engine; storage volume failure or remount read-only; file deleted/truncated concurrently by cleanup scripts.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Failed to create checkpoint file ${fileName}
• WRITER_OPERATION_FAILED
• skipped error
• Failed to create table %s
• Fallback content comparison failed, fallback to COPY. source

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