{"record":{"id":"9b5af4b13c7409d3","repo":"apache/cassandra","slug":"unable-to-list-directory","errorCode":null,"errorMessage":"Unable to list directory ","messagePattern":"Unable to list directory ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/commitlog/CommitLogArchiver.java","lineNumber":281,"sourceCode":"                }\n            }\n            throw new RuntimeException(e);\n        }\n\n        return true;\n    }\n\n    public void maybeRestoreArchive()\n    {\n        if (Strings.isNullOrEmpty(restoreDirectories))\n            return;\n\n        for (String dir : restoreDirectories.split(DELIMITER))\n        {\n            File[] files = new File(dir).tryList();\n            if (files == null)\n            {\n                throw new RuntimeException(\"Unable to list directory \" + dir);\n            }\n            for (File fromFile : files)\n            {\n                CommitLogDescriptor fromHeader = CommitLogDescriptor.fromHeader(fromFile, DatabaseDescriptor.getEncryptionContext());\n                CommitLogDescriptor fromName = CommitLogDescriptor.isValid(fromFile.name()) ? CommitLogDescriptor.fromFileName(fromFile.name()) : null;\n                CommitLogDescriptor descriptor;\n                if (fromHeader == null && fromName == null)\n                    throw new IllegalStateException(\"Cannot safely construct descriptor for segment, either from its name or its header: \" + fromFile.path());\n                else if (fromHeader != null && fromName != null && !fromHeader.equalsIgnoringCompression(fromName))\n                    throw new IllegalStateException(String.format(\"Cannot safely construct descriptor for segment, as name and header descriptors do not match (%s vs %s): %s\", fromHeader, fromName, fromFile.path()));\n                else if (fromName != null && fromHeader == null)\n                    throw new IllegalStateException(\"Cannot safely construct descriptor for segment, as name descriptor implies a version that should contain a header descriptor, but that descriptor could not be read: \" + fromFile.path());\n                else if (fromHeader != null)\n                    descriptor = fromHeader;\n                else descriptor = fromName;\n\n                if (descriptor.version > CommitLogDescriptor.current_version)\n                    throw new IllegalStateException(\"Unsupported commit log version: \" + descriptor.version);","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/commitlog/CommitLogArchiver.java#L263-L299","documentation":"Thrown by maybeRestoreArchive() when a configured restore directory cannot be listed: File.tryList() returned null, meaning the path is not a readable directory (does not exist, is a file, or lacks read permission). Restore cannot proceed without enumerating the archived segments.","triggerScenarios":"maybeRestoreArchive() iterates restore_directories (split on delimiter); for one dir, new File(dir).tryList() returns null.","commonSituations":"Restore directory was deleted between configuration and startup; permissions revoked; path points to a regular file; mount not present in a container.","solutions":["Create the directory with correct ownership: mkdir -p <dir> && chown cassandra:cassandra <dir>.","Verify each restore_directories entry is an existing, readable directory (ls -ld <dir>).","Fix mount/permission issues so the Cassandra process can read the directory.","Remove invalid entries from restore_directories if they are not needed."],"exampleFix":"# before\nrestore_directories: /mnt/old-archive\n# after (directory recreated and readable)\nmkdir -p /mnt/old-archive && chown cassandra:cassandra /mnt/old-archive\nrestore_directories: /mnt/old-archive","handlingStrategy":"validation","validationCode":"for (String dir : restoreDirs.split(\",\")) {\n    File d = new File(dir.trim());\n    if (!d.isDirectory() || !d.canRead())\n        throw new IllegalStateException(\"restore dir missing or unreadable: \" + dir);\n}","typeGuard":null,"tryCatchPattern":"try { node.startup(); }\ncatch (RuntimeException e) {\n    if (e.getMessage().startsWith(\"Unable to list directory\"))\n        log.error(\"Recreate/repair restore directory before restarting\", e);\n    throw e;\n}","preventionTips":["Health-check restore directories before node start","Recreate restore directories as part of restore runbooks","Avoid mounts that may detach silently"],"tags":["cassandra","commitlog","directory","restore"],"backgroundTag":"directory-not-found","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}