{"record":{"id":"b2c499e8ff38d278","repo":"apache/flink","slug":"failed-to-list-contents-of-directory","errorCode":null,"errorMessage":"Failed to list contents of {directory}","messagePattern":"Failed to list contents of (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/util/FileUtils.java","lineNumber":354,"sourceCode":"            // exists but is file, not directory\n            // either an error from the caller, or concurrently a file got created\n            throw new IOException(directory + \" is not a directory\");\n        }\n        // else: does not exist, which is okay (as if deleted)\n    }\n\n    private static void cleanDirectoryInternal(File directory) throws IOException {\n        if (Files.isSymbolicLink(directory.toPath())) {\n            // the user directories which symbolic links point to should not be cleaned.\n            return;\n        }\n        if (directory.isDirectory()) {\n            final File[] files = directory.listFiles();\n\n            if (files == null) {\n                // directory does not exist any more or no permissions\n                if (directory.exists()) {\n                    throw new IOException(\"Failed to list contents of \" + directory);\n                } else {\n                    throw new FileNotFoundException(directory.toString());\n                }\n            }\n\n            // remove all files in the directory\n            for (File file : files) {\n                if (file != null) {\n                    deleteFileOrDirectory(file);\n                }\n            }\n        } else if (directory.exists()) {\n            throw new IOException(directory + \" is not a directory but a regular file\");\n        } else {\n            // else does not exist at all\n            throw new FileNotFoundException(directory.toString());\n        }\n    }","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/util/FileUtils.java#L336-L372","documentation":"Thrown from cleanDirectoryInternal when File.listFiles() returns null while the directory still exists. listFiles() signals an I/O error or permission problem this way (null), so cleaning is impossible: the JVM cannot even enumerate the directory's children.","triggerScenarios":"FileUtils.cleanDirectory/deleteDirectory on a directory without read permission (or execute/search permission on Unix), an I/O error on the underlying disk, or a filesystem in a bad state — while an exists() check confirms the path is still present.","commonSituations":"Directories created by root/another user inside the Flink work dir and later cleaned by the flink user; NFS/network mounts glitching; directories with mode 000 from a misconfigured extraction; Windows ACLs denying enumeration.","solutions":["Check permissions on the directory: it needs read+execute (Unix) or list-directory rights (Windows) for the cleaning user","Fix ownership of the work dir so the Flink process owns its subtree (chown -R)","If the volume is faulty (NFS/disk errors), resolve the mount/storage problem first"],"exampleFix":"# before (as wrong user)\nflink clean-work-dir /opt/flink/work  # dir owned by root, mode 700\n\n# after\nsudo chown -R flink:flink /opt/flink/work\nsudo chmod -R u+rwX /opt/flink/work","handlingStrategy":"validation","validationCode":"File d = new File(dir);\nif (d.isDirectory() && d.list() == null && d.exists()) {\n    throw new IOException(\"No permission to list \" + d + \" - fix ownership/mode before cleanup\");\n}","typeGuard":"boolean canEnumerate(File d) { return !d.exists() || d.list() != null; }","tryCatchPattern":"catch (IOException e) during cleanup: log with the directory path and owning user; cleanup failures of caches can be non-fatal, state dirs usually fatal.","preventionTips":["Ensure the Flink process owns its work/state directories (chown -R flunk:flink ...)","Audit containers and scripts that create root-owned files inside Flink-managed dirs"],"tags":["flink-core","filesystem","permissions","cleanup","io"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}