apache/cassandra · warning

Invalid folder descriptor trying to create log replica

Error message

Invalid folder descriptor trying to create log replica {}. Continuing without Native I/O support.

What it means

LogReplica.create tries to open the transaction log directory with NativeLibrary.tryOpenDirectory to obtain a folder file descriptor used to detect hard-link renames. When the FD is -1, behavior depends on context: in a client/tooling process (isClientInitialized) it logs this warning and continues without native I/O support; in a server process it throws FSReadError because the server requires FDs for correct txn-log tracking.

Solutions

1. If seen in a client tool, ignore — operation continues without native I/O support.
2. If seen on a server (FSReadError), fix permissions on the data/txn-log directory so the process can open it.
3. Verify the platform native library is present and seccomp profiles allow open() syscalls on the directory.
4. Ensure the directory path exists and is a real directory before invoking the tool.

Example fix

// before (docker run with blocking profile)
docker run --security-opt seccomp=strict.json cassandra ...
// after
docker run --security-opt seccomp=default.json cassandra ...

// Pre-check the directory is openable before running tools
try (java.nio.channels.FileChannel ch = FileChannel.open(Paths.get(dir), StandardOpenOption.READ)) {
    // directory readable
}
catch (IOException e) {
    throw new IllegalStateException("Cannot open txn log directory: " + dir, e);
}

try { LogReplica.create(file); }
catch (FSReadError e) {
    logger.error("Directory FD unavailable: {}", e.getMessage());
    // fix permissions / seccomp and retry
}

When it happens

Trigger: tryOpenDirectory returns -1 for the log directory path — e.g. the directory does not exist, lacks read permission, or the platform lacks the native library (non-Linux/limited seccomp blocking openat) — while REQUIRE_FD is true; run inside a client tool (e.g. sstable tools) to get the warn variant.

Common situations: Running Cassandra client tools on macOS/Windows without full native support; containers with restrictive seccomp/AppArmor profiles blocking directory open; data directories mounted with restrictive permissions.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• --all-tables option should be passed along with --keyspace…
• Altering permissions on builtin functions is not supported
• close( ) failed, errno ( ).
• CloudstackSnitch cannot access lease file.
• Could not list files in

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

Appendix: source

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

 * @see LogFile
 */
final class LogReplica implements AutoCloseable
{
    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());

View on GitHub (pinned to 88fd0f6a0e)