apache/seatunnel · error · CheckpointStorageException

Failed to create checkpoint file

Error message

Failed to create checkpoint file ${fileName}

What it means

LocalFileStorage.storeCheckPoint creates the target checkpoint file via FileUtils.touch; an IOException there is wrapped as 'Failed to create checkpoint file <fileName>'. The storage layer could not create (touch) the file at the computed path, so nothing was written.

Solutions

1. Ensure the configured storage parent directory exists and is writable by the process user (mkdir/chown as needed).
2. Check disk space and that the filesystem is not mounted read-only.
3. Validate the configured path is absolute and valid for the OS (Windows drive letters, path length).
4. Re-run the job after fixing permissions/space; the touch failure is environmental, not transient by nature.

Example fix

// before
# storage dir owned by root, engine runs as seatunnel
mkdir -p /data/seatunnel/checkpoint-storage && chown -R seatunnel:seatunnel /data/seatunnel/checkpoint-storage
// after
# storage dir writable, checkpoint persists normally

java.io.File dir = new java.io.File(storageParentDir);
if (!dir.exists() && !dir.mkdirs())
    throw new IllegalStateException("Cannot create storage dir: " + dir);
if (!dir.canWrite())
    throw new IllegalStateException("Storage dir not writable: " + dir);

boolean storageDirWritable(String parentDir) {
    java.io.File d = new java.io.File(parentDir);
    return d.isDirectory() && d.canWrite();
}

try {
    storage.storeCheckPoint(state);
} catch (CheckpointStorageException e) {
    if (e.getMessage().startsWith("Failed to create checkpoint file")) {
        // check disk space and directory permissions before retrying
    }
    throw e;
}

When it happens

Trigger: storeCheckPoint called when the target directory does not exist and cannot be created, the path is invalid for the OS, or the process lacks write permission on the parent directory; also on disk-full or path-length limits.

Common situations: Running the engine as a user without write access to the configured storage parent directory; storage parent dir deleted at runtime; wrong path separators/drive letters in the configured directory; read-only or full filesystem.

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 write checkpoint data to file
• Creating database exception.
• Error during file discovery
• Failed to delete checkpoint directory
• Fallback content comparison failed, fallback to COPY…

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

Appendix: 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:102

    public String storeCheckPoint(PipelineState state) throws CheckpointStorageException {
        byte[] datas;
        try {
            datas = serializeCheckPointData(state);
        } catch (IOException e) {
            throw new CheckpointStorageException("Failed to serialize checkpoint data", e);
        }
        // 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<>();
        }

View on GitHub (pinned to cf67b549a7)