{"record":{"id":"71790283e70ebcc7","repo":"apache/cassandra","slug":"failed-to-list-files-in-s","errorCode":null,"errorMessage":"Failed to list files in %s","messagePattern":"Failed to list files in (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/lifecycle/LogAwareFileLister.java","lineNumber":83,"sourceCode":"    NavigableMap<File, Directories.FileType> files = new TreeMap<>();\n\n    @VisibleForTesting\n    LogAwareFileLister(Path folder, BiPredicate<File, FileType> filter, OnTxnErr onTxnErr)\n    {\n        this.folder = folder;\n        this.filter = filter;\n        this.onTxnErr = onTxnErr;\n    }\n\n    public List<File> list()\n    {\n        try\n        {\n            return innerList();\n        }\n        catch (Throwable t)\n        {\n            throw new RuntimeException(String.format(\"Failed to list files in %s\", folder), t);\n        }\n    }\n\n    List<File> innerList() throws Throwable\n    {\n        list(Files.newDirectoryStream(folder))\n        .stream()\n        .filter((f) -> !LogFile.isLogFile(f))\n        .forEach((f) -> files.put(f, FileType.FINAL));\n\n        // Since many file systems are not atomic, we cannot be sure we have listed a consistent disk state\n        // (Linux would permit this, but for simplicity we keep our behaviour the same across platforms)\n        // so we must be careful to list txn log files AFTER every other file since these files are deleted last,\n        // after all other files are removed\n        list(Files.newDirectoryStream(folder, '*' + LogFile.EXT))\n        .stream()\n        .filter(LogFile::isLogFile)\n        .forEach(this::classifyFiles);","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/lifecycle/LogAwareFileLister.java#L65-L101","documentation":"LogAwareFileLister lists SSTable/component files in a data directory while replaying transaction (txn compaction) logs. If any I/O or parsing error occurs during innerList(), it is wrapped in a RuntimeException 'Failed to list files in <folder>' so the caller knows directory listing failed, with the original cause attached.","triggerScenarios":"Calling list() (via LifecycleTransaction/SSTableLister paths, e.g. during startup SSTable discovery) when Files.newDirectoryStream(folder) throws (directory missing/unreadable) or LogFile record parsing fails inside innerList().","commonSituations":"Data directory removed or renamed while Cassandra runs; filesystem permission changes; NFS/S3 mounts flaking; corrupted or truncated transaction log files being read during startup after a crash.","solutions":["Check the wrapped cause (t) to see the underlying filesystem or parse error","Verify the data folder exists and is readable by the Cassandra process (ls -la, permissions, mount health)","Repair or remove corrupted txn_compaction.log files (back up first, follow Cassandra docs for aborted transaction logs)","If the directory was moved, restore it or update cassandra.yaml data_file_directories and restart","Run nodetool drain before restarts to keep transaction logs in a consistent state"],"exampleFix":"// before: directory moved\n-rw data_file_directories: [/mnt/old-disk/cassandra/data]\n// after\n-rw data_file_directories: [/mnt/new-disk/cassandra/data]\nsudo chown -R cassandra:cassandra /mnt/new-disk/cassandra/data","handlingStrategy":"try-catch","validationCode":"File dir = new File(folder);\nif (!dir.isDirectory() || !dir.canRead())\n    throw new IOException(\"Data folder missing or unreadable: \" + folder);","typeGuard":null,"tryCatchPattern":"try {\n    files = lister.list();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to list files in\")) {\n        logger.error(\"Directory listing failed: {}\", e.getCause(), e);\n        // fix filesystem access or restore directory before retry\n    } else throw e;\n}","preventionTips":["Monitor data directories for existence and readability (Nagios/Prometheus node_exporter fs metrics)","Never move or rename data dirs while the node runs; use nodetool drain first","Set sane ulimits and keep filesystems mounted before systemd starts Cassandra","Back up complete directories (sstables + txn logs) as a unit"],"tags":["filesystem","sstable","startup"],"backgroundTag":"file-read-failed","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"}