{"record":{"id":"a93504b464a15f7e","repo":"apache/cassandra","slug":"invalid-folder-descriptor-trying-to-create-log-rep","errorCode":null,"errorMessage":"Invalid folder descriptor trying to create log replica %s","messagePattern":"Invalid folder descriptor trying to create log replica (.+?)","errorType":"exception","errorClass":"FSReadError","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/lifecycle/LogReplica.java","lineNumber":69,"sourceCode":"    private static final Logger logger = LoggerFactory.getLogger(LogReplica.class);\n    private static final boolean REQUIRE_FD = !IGNORE_MISSING_NATIVE_FILE_HINTS.getBoolean();\n\n    private final File file;\n    private int directoryDescriptor;\n    private final Map<String, String> errors = new HashMap<>();\n\n    static LogReplica create(File directory, String fileName)\n    {\n        int folderFD = NativeLibrary.tryOpenDirectory(directory.path());\n        if (folderFD == -1  && REQUIRE_FD)\n        {\n            if (DatabaseDescriptor.isClientInitialized())\n            {\n                logger.warn(\"Invalid folder descriptor trying to create log replica {}. Continuing without Native I/O support.\", directory.path());\n            }\n            else\n            {\n                throw new FSReadError(new IOException(String.format(\"Invalid folder descriptor trying to create log replica %s\", directory.path())), directory.path());\n            }\n        }\n\n        return new LogReplica(new File(fileName), folderFD);\n    }\n\n    static LogReplica open(File file)\n    {\n        int folderFD = NativeLibrary.tryOpenDirectory(file.parent().path());\n        if (folderFD == -1)\n        {\n            if (DatabaseDescriptor.isClientInitialized())\n            {\n                logger.warn(\"Invalid folder descriptor trying to create log replica {}. Continuing without Native I/O support.\", file.parentPath());\n            }\n            else\n            {\n                throw new FSReadError(new IOException(String.format(\"Invalid folder descriptor trying to create log replica %s\", file.parent().path())), file.parent().path());","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/lifecycle/LogReplica.java#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the directory exists and is accessible (permissions, ownership) at the reported path","Raise the open-file limit for the Cassandra process (ulimit -n / systemd LimitNOFILE)","Verify the filesystem mount is healthy and not read-only","If this happens in an offline tool, pass a correct data directory path","Restart the node after fixing the filesystem condition"],"exampleFix":"// before (systemd)\nLimitNOFILE=10000\n// after\nLimitNOFILE=100000","handlingStrategy":"try-catch","validationCode":"File dir = new File(path);\nif (!dir.isDirectory() || !dir.canRead()) throw new IOException(\"Bad txn log folder: \" + path);\nif (new File(\"/proc/self/fd\").list().length > fdLimit * 0.9) logger.warn(\"fd usage near limit\");","typeGuard":null,"tryCatchPattern":"try {\n    replica = LogReplica.create(folder);\n} catch (FSReadError e) {\n    if (String.valueOf(e.getMessage()).startsWith(\"Invalid folder descriptor\")) {\n        logger.error(\"Check permissions/fd limits/mount for {}\", folder, e);\n    } else throw e;\n}","preventionTips":["Raise LimitNOFILE (systemd) / ulimit -n well above default for Cassandra","Alert on fd usage (lsof count) before exhaustion","Ensure data directories exist with correct ownership before service start","Validate paths passed to offline tools (sstablesplit, offline compaction)"],"tags":["filesystem","transaction-log","file-descriptor"],"backgroundTag":"file-open-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}