{"record":{"id":"3df6d7c0cd249319","repo":"apache/pulsar","slug":"unable-to-list-directory-content-in-directory","errorCode":null,"errorMessage":"Unable to list directory content in: ${directory}","messagePattern":"Unable to list directory content in: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/nar/FileUtils.java","lineNumber":153,"sourceCode":"     * this is printed at warn to the given logger.\n     *\n     * @param directory to delete contents of\n     * @param filter if null then no filter is used\n     * @param recurse will look for contents of sub directories.\n     * @param deleteEmptyDirectories default is false; if true will delete\n     * directories found that are empty\n     * @throws IOException if abstract pathname does not denote a directory, or\n     * if an I/O error occurs\n     */\n    public static void deleteFilesInDirectory(\n        final File directory, final FilenameFilter filter,\n        final boolean recurse, final boolean deleteEmptyDirectories) throws IOException {\n        // ensure the specified directory is actually a directory and that it exists\n        if (null != directory && directory.isDirectory()) {\n            final File ingestFiles[] = directory.listFiles();\n            if (ingestFiles == null) {\n                // null if abstract pathname does not denote a directory, or if an I/O error occurs\n                throw new IOException(\"Unable to list directory content in: \" + directory.getAbsolutePath());\n            }\n            for (File ingestFile : ingestFiles) {\n                boolean process = (filter == null) ? true : filter.accept(directory, ingestFile.getName());\n                if (ingestFile.isFile() && process) {\n                    FileUtils.deleteFile(ingestFile, 3);\n                }\n                if (ingestFile.isDirectory() && recurse) {\n                    FileUtils.deleteFilesInDirectory(ingestFile, filter, recurse, deleteEmptyDirectories);\n                    String[] ingestFileList = ingestFile.list();\n                    if (deleteEmptyDirectories && ingestFileList != null && ingestFileList.length == 0) {\n                        FileUtils.deleteFile(ingestFile, 3);\n                    }\n                }\n            }\n        }\n    }\n\n    /**","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/nar/FileUtils.java#L135-L171","documentation":"FileUtils.deleteFilesInDirectory lists the directory via File.listFiles() before deleting entries; listFiles() returns null not only for non-directories but also when an I/O error occurs while listing, in which case the method throws IOException 'Unable to list directory content in: <abs path>'. This guards against silently treating an unreadable directory as empty.","triggerScenarios":"deleteFilesInDirectory called on a directory that exists (isDirectory() true) but whose entries cannot be enumerated: permission denied on readdir, the directory vanishing mid-scan, or filesystem/IO errors (NFS stale handle).","commonSituations":"Cleanup tasks for NAR unpack directories racing with external deletion, stale NFS handles after a server restart, or permission changes applied while the process runs.","solutions":["Verify the process can list the path (ls as the service user).","Check dmesg/mount status for stale NFS handles and remount the share.","Re-grant read+execute permission on the directory (readdir needs r and x).","Ensure no external process deletes/recreates the directory concurrently."],"exampleFix":"// before\nFileUtils.deleteFilesInDirectory(dir, filter, true, true);\n// after\nif (dir != null && dir.canRead()) {\n    FileUtils.deleteFilesInDirectory(dir, filter, true, true);\n} else {\n    log.warn(\"skipping cleanup, cannot read {}\", dir);\n}","handlingStrategy":"retry","validationCode":"if (directory != null && directory.isDirectory() && !directory.canRead()) {\n    log.warn(\"Skipping cleanup: cannot read {}\", directory);\n    return;\n}","typeGuard":null,"tryCatchPattern":"try {\n    FileUtils.deleteFilesInDirectory(dir, null, true, true);\n} catch (IOException e) {\n    if (e.getMessage().startsWith(\"Unable to list directory content\")) {\n        // transient IO/race: log and retry later, don't crash the cleanup loop\n        log.warn(\"Directory listing failed for {}, will retry next cycle\", dir, e);\n        return;\n    }\n    throw e;\n}","preventionTips":["Avoid concurrent deletion/recreation of the same directory by external tooling","Monitor NFS mounts for stale handles in cleanup jobs","Keep read+execute permissions on directories subject to automated cleanup"],"tags":["filesystem","io","directory-listing","cleanup"],"backgroundTag":"directory-listing-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}