{"record":{"id":"76d9f68ceae6225e","repo":"apache/seatunnel","slug":"failed-to-write-checkpoint-data-to-file-filename","errorCode":null,"errorMessage":"Failed to write checkpoint data to file ${fileName}","messagePattern":"Failed to write checkpoint data to 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":108,"sourceCode":"        }\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        }\n\n        Collection<File> fileList;\n        try {\n            fileList = FileUtils.listFiles(filePath, FILE_EXTENSIONS, true);\n        } catch (Exception e) {\n            throw new CheckpointStorageException(","sourceCodeStart":90,"sourceCodeEnd":126,"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#L90-L126","documentation":"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.","triggerScenarios":"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.","commonSituations":"Disk-full conditions on the node running the engine; storage volume failure or remount read-only; file deleted/truncated concurrently by cleanup scripts.","solutions":["Free disk space / check df -h on the storage volume, then re-run the job (checkpointing will retry on the next trigger).","Check filesystem health (dmesg, mount options) and ensure it is writable.","Remove the leftover empty/partial checkpoint file before retrying so stale files don't confuse readers.","Exclude the storage directory from aggressive cleanup scripts that could delete files mid-write."],"exampleFix":"// before\n$ df -h /data/seatunnel\n/dev/sda1  100G  100G  0  100% /data\n// after\n$ df -h /data/seatunnel\n/dev/sda1  100G   62G   38G  62% /data  # checkpoint write succeeds","handlingStrategy":"retry","validationCode":"java.io.File dir = new java.io.File(storageParentDir);\nlong usable = dir.getUsableSpace();\nif (usable < 512L * 1024 * 1024)\n    throw new IllegalStateException(\"Low disk space on checkpoint storage: \" + usable + \" bytes free\");","typeGuard":null,"tryCatchPattern":"try {\n    storage.storeCheckPoint(state);\n} catch (CheckpointStorageException e) {\n    if (e.getMessage().startsWith(\"Failed to write checkpoint data to file\")) {\n        // likely disk-full/IO error: free space or check volume health, then retry\n    }\n    throw e;\n}","preventionTips":["Alert on disk usage for the checkpoint storage volume (e.g. >85%).","Clean up leftover partial checkpoint files after write failures before retrying.","Exclude the storage directory from external cleanup scripts that could interfere mid-write."],"tags":["file","io","local-file","write"],"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"}