apache/cassandra · error · FSReadError

Invalid folder descriptor trying to create log replica

Error message

Invalid folder descriptor trying to create log replica %s

What it means

LogReplica.create opens a file descriptor for the directory holding a transaction log replica using Native I/O (posix_fadvise-style calls). If the folder's file descriptor is invalid (open failed), Cassandra logs a warning and continues without Native I/O when running in client/tool mode (DatabaseDescriptor.isClientInitialized()), but throws FSReadError with this message for a normal server process.

Solutions

1. Check the directory exists and is accessible (permissions, ownership) at the reported path
2. Raise the open-file limit for the Cassandra process (ulimit -n / systemd LimitNOFILE)
3. Verify the filesystem mount is healthy and not read-only
4. If this happens in an offline tool, pass a correct data directory path
5. Restart the node after fixing the filesystem condition

Example fix

// before (systemd)
LimitNOFILE=10000
// after
LimitNOFILE=100000

File dir = new File(path);
if (!dir.isDirectory() || !dir.canRead()) throw new IOException("Bad txn log folder: " + path);
if (new File("/proc/self/fd").list().length > fdLimit * 0.9) logger.warn("fd usage near limit");

try {
    replica = LogReplica.create(folder);
} catch (FSReadError e) {
    if (String.valueOf(e.getMessage()).startsWith("Invalid folder descriptor")) {
        logger.error("Check permissions/fd limits/mount for {}", folder, e);
    } else throw e;
}

When it happens

Trigger: Creating a log replica for a transaction log directory whose open() fails: directory deleted mid-operation, bad permissions, fd exhaustion, or native I/O returning an invalid descriptor.

Common situations: Filesystem unmounted or folder removed under a running node; too many open files (ulimit -n) exhausting descriptors; permission changes on the data directory; running tools (sstablesplit, offline compaction) against a bad path.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• 3
• Cannot delete the directory
• Cannot move the file
• Cannot remove temporary or obsoleted files for
• Cannot remove temporary or obsoleted files for

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

Appendix: source

Thrown at src/java/org/apache/cassandra/db/lifecycle/LogReplica.java:69

    private static final Logger logger = LoggerFactory.getLogger(LogReplica.class);
    private static final boolean REQUIRE_FD = !IGNORE_MISSING_NATIVE_FILE_HINTS.getBoolean();

    private final File file;
    private int directoryDescriptor;
    private final Map<String, String> errors = new HashMap<>();

    static LogReplica create(File directory, String fileName)
    {
        int folderFD = NativeLibrary.tryOpenDirectory(directory.path());
        if (folderFD == -1  && REQUIRE_FD)
        {
            if (DatabaseDescriptor.isClientInitialized())
            {
                logger.warn("Invalid folder descriptor trying to create log replica {}. Continuing without Native I/O support.", directory.path());
            }
            else
            {
                throw new FSReadError(new IOException(String.format("Invalid folder descriptor trying to create log replica %s", directory.path())), directory.path());
            }
        }

        return new LogReplica(new File(fileName), folderFD);
    }

    static LogReplica open(File file)
    {
        int folderFD = NativeLibrary.tryOpenDirectory(file.parent().path());
        if (folderFD == -1)
        {
            if (DatabaseDescriptor.isClientInitialized())
            {
                logger.warn("Invalid folder descriptor trying to create log replica {}. Continuing without Native I/O support.", file.parentPath());
            }
            else
            {
                throw new FSReadError(new IOException(String.format("Invalid folder descriptor trying to create log replica %s", file.parent().path())), file.parent().path());

View on GitHub (pinned to 88fd0f6a0e)