apache/seatunnel · error · CheckpointStorageException

Failed to create checkpoint file ${fileName}

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.

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)

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 ${fileName}
• skipped error
• Creating database %s exception.
• Fallback content comparison failed, fallback to COPY. source
• Error during file discovery

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