{"record":{"id":"0fa68c2765b577aa","repo":"apache/seatunnel","slug":"failed-to-create-checkpoint-file-filename","errorCode":null,"errorMessage":"Failed to create checkpoint file ${fileName}","messagePattern":"Failed to create checkpoint file (.+?)","errorType":"exception","errorClass":"CheckpointStorageException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-local-file/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/localfile/LocalFileStorage.java","lineNumber":102,"sourceCode":"    public String storeCheckPoint(PipelineState state) throws CheckpointStorageException {\n        byte[] datas;\n        try {\n            datas = serializeCheckPointData(state);\n        } catch (IOException e) {\n            throw new CheckpointStorageException(\"Failed to serialize checkpoint data\", e);\n        }\n        // Consider file paths for different operating systems\n        String fileName =\n                getStorageParentDirectory()\n                        + state.getJobId()\n                        + File.separator\n                        + getCheckPointName(state);\n\n        File file = new File(fileName);\n        try {\n            FileUtils.touch(file);\n        } catch (IOException e) {\n            throw new CheckpointStorageException(\"Failed to create checkpoint file \" + fileName, e);\n        }\n\n        try {\n            FileUtils.writeByteArrayToFile(file, datas);\n        } catch (IOException e) {\n            throw new CheckpointStorageException(\n                    \"Failed to write checkpoint data to file \" + fileName, e);\n        }\n\n        return fileName;\n    }\n\n    @Override\n    public List<PipelineState> getAllCheckpoints(String jobId) throws CheckpointStorageException {\n        File filePath = new File(getStorageParentDirectory() + jobId);\n        if (!filePath.exists()) {\n            return new ArrayList<>();\n        }","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-local-file/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/localfile/LocalFileStorage.java#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the configured storage parent directory exists and is writable by the process user (mkdir/chown as needed).","Check disk space and that the filesystem is not mounted read-only.","Validate the configured path is absolute and valid for the OS (Windows drive letters, path length).","Re-run the job after fixing permissions/space; the touch failure is environmental, not transient by nature."],"exampleFix":"// before\n# storage dir owned by root, engine runs as seatunnel\nmkdir -p /data/seatunnel/checkpoint-storage && chown -R seatunnel:seatunnel /data/seatunnel/checkpoint-storage\n// after\n# storage dir writable, checkpoint persists normally","handlingStrategy":"validation","validationCode":"java.io.File dir = new java.io.File(storageParentDir);\nif (!dir.exists() && !dir.mkdirs())\n    throw new IllegalStateException(\"Cannot create storage dir: \" + dir);\nif (!dir.canWrite())\n    throw new IllegalStateException(\"Storage dir not writable: \" + dir);","typeGuard":"boolean storageDirWritable(String parentDir) {\n    java.io.File d = new java.io.File(parentDir);\n    return d.isDirectory() && d.canWrite();\n}","tryCatchPattern":"try {\n    storage.storeCheckPoint(state);\n} catch (CheckpointStorageException e) {\n    if (e.getMessage().startsWith(\"Failed to create checkpoint file\")) {\n        // check disk space and directory permissions before retrying\n    }\n    throw e;\n}","preventionTips":["Pre-create the storage parent directory with correct ownership before starting the engine.","Monitor disk space and mount status on the checkpoint storage volume.","Use absolute, OS-valid paths in the storage configuration."],"tags":["file","io","local-file","permission"],"backgroundTag":"file-write-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}