{"record":{"id":"8aefea0686874cd4","repo":"apache/seatunnel","slug":"failed-to-list-files-from-names-path","errorCode":null,"errorMessage":"Failed to list files from names${path}","messagePattern":"Failed to list files from names(.+?)","errorType":"exception","errorClass":"CheckpointStorageException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-hdfs/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/hdfs/HdfsStorage.java","lineNumber":350,"sourceCode":"                });\n    }\n\n    public List<String> getFileNames(String path) throws CheckpointStorageException {\n        try {\n            Path parentPath = new Path(path);\n            if (!fs.exists(parentPath)) {\n                log.info(\"Path \" + path + \" is not a directory\");\n                return new ArrayList<>();\n            }\n            FileStatus[] fileStatus =\n                    fs.listStatus(parentPath, path1 -> path1.getName().endsWith(FILE_FORMAT));\n            List<String> fileNames = new ArrayList<>();\n            for (FileStatus status : fileStatus) {\n                fileNames.add(status.getPath().getName());\n            }\n            return fileNames;\n        } catch (IOException e) {\n            throw new CheckpointStorageException(\"Failed to list files from names\" + path, e);\n        }\n    }\n\n    /**\n     * Get checkpoint name\n     *\n     * @param fileName file name\n     * @return checkpoint data\n     */\n    private PipelineState readPipelineState(String fileName, String jobId)\n            throws CheckpointStorageException {\n        fileName =\n                getStorageParentDirectory() + jobId + DEFAULT_CHECKPOINT_FILE_PATH_SPLIT + fileName;\n        try (FSDataInputStream in = fs.open(new Path(fileName));\n                ByteArrayOutputStream stream = new ByteArrayOutputStream()) {\n            IOUtils.copyBytes(in, stream, 1024);\n            byte[] bytes = stream.toByteArray();\n            return deserializeCheckPointData(bytes);","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-hdfs/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/hdfs/HdfsStorage.java#L332-L368","documentation":"HdfsStorage.getFileNames lists files under a directory on the HDFS filesystem; if the underlying FileSystem.listStatus (or equivalent) call throws IOException, it wraps it in CheckpointStorageException with the path included. This is an I/O-level failure to enumerate the directory, not a 'no files' condition.","triggerScenarios":"Calling any API that lists job directories (getCheckpoint, deleteCheckpoint, getAllCheckpoints) when HDFS is unreachable, the directory does not exist on that filesystem, or listing fails due to permissions/Namenode errors.","commonSituations":"Wrong fs.defaultFS / storage path configuration; HDFS Namenode down or in safe mode; Kerberos/auth issues causing access failures; network partition between client and HDFS.","solutions":["Check HDFS connectivity and that the Namenode is up (hdfs dfs -ls <path> works from the same host).","Verify the storage parent directory path and fs configuration (fs.defaultFS, core-site.xml/hdfs-site.xml on classpath).","Check HDFS permissions for the running user on the job directory.","Retry with backoff if the cluster was temporarily unavailable."],"exampleFix":"// before\nList<String> names = storage.getAllCheckpoints();\n// after\nRetryer<String> retryer = Retryer.ofBackoff(3, Duration.ofSeconds(2));\nList<String> names = retryer.call(() -> storage.getAllCheckpoints());","handlingStrategy":"retry","validationCode":"// Pre-check HDFS reachability before listing\norg.apache.hadoop.fs.FileSystem fs =\n    org.apache.hadoop.fs.FileSystem.get(conf);\nboolean reachable = fs.exists(new org.apache.hadoop.fs.Path(storageParentDir));","typeGuard":"boolean jobDirListable(String jobId) {\n    try { storage.getCheckpointsByJobIdAndPipelineId(jobId, pipelineId); return true; }\n    catch (CheckpointStorageException e) { return false; }\n}","tryCatchPattern":"int attempts = 0;\nwhile (true) {\n    try { return storage.getAllCheckpoints(); }\n    catch (CheckpointStorageException e) {\n        if (e.getMessage().startsWith(\"Failed to list files\") && ++attempts < 3) {\n            Thread.sleep(1000L * attempts); continue;\n        }\n        throw e;\n    }\n}","preventionTips":["Monitor HDFS Namenode health and safe-mode status before running storage operations.","Keep core-site.xml/hdfs-site.xml on the classpath with correct fs.defaultFS.","Ensure the running user has read permission on the storage parent directory."],"tags":["hdfs","io","list","storage"],"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-14T11:17:12.474Z"}