What causes "Failed to list files in %s" in apache/cassandra?

Check the wrapped cause (t) to see the underlying filesystem or parse error

apache/cassandra · error · RuntimeException

Failed to list files in %s

Error message

Failed to list files in %s

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/db/lifecycle/LogAwareFileLister.java:83

    NavigableMap<File, Directories.FileType> files = new TreeMap<>();

    @VisibleForTesting
    LogAwareFileLister(Path folder, BiPredicate<File, FileType> filter, OnTxnErr onTxnErr)
    {
        this.folder = folder;
        this.filter = filter;
        this.onTxnErr = onTxnErr;
    }

    public List<File> list()
    {
        try
        {
            return innerList();
        }
        catch (Throwable t)
        {
            throw new RuntimeException(String.format("Failed to list files in %s", folder), t);
        }
    }

    List<File> innerList() throws Throwable
    {
        list(Files.newDirectoryStream(folder))
        .stream()
        .filter((f) -> !LogFile.isLogFile(f))
        .forEach((f) -> files.put(f, FileType.FINAL));

        // Since many file systems are not atomic, we cannot be sure we have listed a consistent disk state
        // (Linux would permit this, but for simplicity we keep our behaviour the same across platforms)
        // so we must be careful to list txn log files AFTER every other file since these files are deleted last,
        // after all other files are removed
        list(Files.newDirectoryStream(folder, '*' + LogFile.EXT))
        .stream()
        .filter(LogFile::isLogFile)
        .forEach(this::classifyFiles);

View on GitHub (pinned to 88fd0f6a0e)

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

Example fix

// before: directory moved
-rw data_file_directories: [/mnt/old-disk/cassandra/data]
// after
-rw data_file_directories: [/mnt/new-disk/cassandra/data]
sudo chown -R cassandra:cassandra /mnt/new-disk/cassandra/data

Defensive patterns

Strategy: try-catch

Validate before calling

File dir = new File(folder);
if (!dir.isDirectory() || !dir.canRead())
    throw new IOException("Data folder missing or unreadable: " + folder);

Try / catch

try {
    files = lister.list();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to list files in")) {
        logger.error("Directory listing failed: {}", e.getCause(), e);
        // fix filesystem access or restore directory before retry
    } else throw e;
}

Prevention

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

When it happens

Trigger: 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().

Common situations: 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.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/71790283e70ebcc7. Report an issue: GitHub.