{"record":{"id":"d241097b154a1b90","repo":"apache/seatunnel","slug":"failed-to-get-all-checkpoints-for-job-jobid","errorCode":null,"errorMessage":"Failed to get all checkpoints for job ${jobId}","messagePattern":"Failed to get all checkpoints for job (.+?)","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":126,"sourceCode":"            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(\n                    \"Failed to get all checkpoints for job \" + jobId, e);\n        }\n        if (fileList.isEmpty()) {\n            log.info(\"No checkpoint found for this job, the job id is: \" + jobId);\n            return new ArrayList<>();\n        }\n        List<PipelineState> states = new ArrayList<>();\n        fileList.forEach(\n                file -> {\n                    try {\n                        byte[] data = FileUtils.readFileToByteArray(file);\n                        states.add(deserializeCheckPointData(data));\n                    } catch (IOException e) {\n                        log.error(\n                                \"Failed to read checkpoint data from file \"\n                                        + file.getAbsolutePath(),\n                                e);\n                    }","sourceCodeStart":108,"sourceCodeEnd":144,"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#L108-L144","documentation":"LocalFileStorage.getAllCheckpoints throws CheckpointStorageException when recursively listing checkpoint data files under the job's storage directory fails. The library wraps any exception from FileUtils.listFiles (IO errors, permission problems, path issues) into this checked storage exception so callers of the checkpoint storage SPI get a uniform error type. It is thrown before any checkpoint deserialization happens, so it indicates filesystem-level failure, not corrupt checkpoint data.","triggerScenarios":"Calling getAllCheckpoints(jobId) when the job's checkpoint directory is unreadable (permission denied), the path is a file instead of a directory, an IO error occurs during directory traversal (e.g. disk error, symlink loop), or the underlying storage mount (NFS) becomes unavailable mid-listing.","commonSituations":"Running the Zeta engine as a different user than the one that wrote the checkpoints; checkpoint directory on a detached/unmounted NFS volume; directory permissions changed by an admin or cleanup job; storage parent path misconfigured so jobId resolves under a non-directory path.","solutions":["Check OS permissions on the checkpoint storage directory and ensure the process user can read/traverse it: ls -la on getStorageParentDirectory()+jobId.","Verify the checkpoint storage parent path configuration points at an existing, mounted directory.","If on NFS/network storage, confirm the mount is alive and retry the job or recovery.","Check the cause exception attached to the CheckpointStorageException for the exact filesystem error."],"exampleFix":"// before\nfileList = FileUtils.listFiles(filePath, FILE_EXTENSIONS, true);\n// after (pre-validate the directory before listing)\nif (!Files.isDirectory(filePath)) {\n    log.warn(\"Checkpoint directory missing for job \" + jobId + \", returning empty\");\n    return new ArrayList<>();\n}\nfileList = FileUtils.listFiles(filePath, FILE_EXTENSIONS, true);","handlingStrategy":"try-catch","validationCode":"// Java: verify the job checkpoint directory is readable before recovery\njava.nio.file.Path dir = java.nio.file.Path.of(storageParentDir, jobId);\nif (!java.nio.file.Files.isDirectory(dir) || !java.nio.file.Files.isReadable(dir)) {\n    throw new IllegalStateException(\"Checkpoint dir missing or unreadable: \" + dir);\n}","typeGuard":"static boolean isReadableDirectory(Path p) {\n    return p != null && Files.isDirectory(p) && Files.isReadable(p);\n}","tryCatchPattern":"try {\n    checkpoints = storage.getAllCheckpoints(jobId);\n} catch (CheckpointStorageException e) {\n    log.error(\"Cannot list checkpoints for job {} (check perms/mount): {}\", jobId, e.getMessage(), e);\n    throw e; // recovery cannot proceed without checkpoint data\n}","preventionTips":["Run the engine under a user with persistent read access to the checkpoint storage directory.","Use a stable, always-mounted path for checkpoint storage; avoid removable/ephemeral mounts.","Do not chmod or clean the checkpoint directory while jobs are running or recovering.","Always inspect the cause chain of CheckpointStorageException — the root filesystem error is attached."],"tags":["checkpoint","local-file-storage","filesystem-io","recovery"],"backgroundTag":"file-read-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"}