apache/cassandra · critical · FSWriteError

Unable to create directory " + dir

Error message

Unable to create directory " + dir

What it means

During Directories construction Cassandra verifies/creates the data directory hierarchy (keyspace/table subdirectories, backups, snapshots). If a directory does not exist and tryCreateDirectories() fails (and it does not exist as a directory afterwards), it throws FSWriteError wrapping an IOException 'Unable to create directory <dir>'.

Source

Thrown at src/java/org/apache/cassandra/db/Directories.java:1314

                                                              .list()
                                                              .keySet()
                                                              .spliterator(), Spliterator.DISTINCT, false)
                                                .map(d -> d.id);

        return builder.generator(curIds);
    }

    private static File getOrCreate(File base, String... subdirs)
    {
        File dir = subdirs == null || subdirs.length == 0 ? base : new File(base, join(subdirs));
        if (dir.exists())
        {
            if (!dir.isDirectory())
                throw new AssertionError(String.format("Invalid directory path %s: path exists but is not a directory", dir));
        }
        else if (!dir.tryCreateDirectories() && !(dir.exists() && dir.isDirectory()))
        {
            throw new FSWriteError(new IOException("Unable to create directory " + dir), dir);
        }
        return dir;
    }

    public static Optional<File> get(File base, String... subdirs)
    {
        File dir = subdirs == null || subdirs.length == 0 ? base : new File(base, join(subdirs));
        return dir.exists() ? Optional.of(dir) : Optional.empty();
    }

    public static File getWithoutCreation(File base, String... subdirs)
    {
        return subdirs == null || subdirs.length == 0 ? base : new File(base, join(subdirs));
    }

    private static String join(String... s)
    {
        return StringUtils.join(s, File.pathSeparator());

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Fix ownership/permissions: `chown -R cassandra:cassandra <data_dir>` and ensure the directory is writable (chmod 755).
  2. Check the filesystem is not read-only (`mount | grep ro`) and remount read-write; free space if the disk is full.
  3. Verify data_file_directories paths in cassandra.yaml exist or their parents are creatable by the cassandra user.
  4. Check SELinux/AppArmor audit logs and adjust policy or contexts (`restorecon -R`) if denials are recorded.

Example fix

// before (running as wrong user or wrong perms)
$ ls -ld /var/lib/cassandra/data
drwxr-xr-x root root
// after
$ sudo chown -R cassandra:cassandra /var/lib/cassandra
$ sudo systemctl restart cassandra
Defensive patterns

Strategy: validation

Validate before calling

Path dir = Paths.get(dataDir, ks, table);
Files.createDirectories(dir.getParent());
if (!Files.isWritable(dir.getParent())) throw new IllegalStateException("Not writable: " + dir);

Try / catch

try {
    new Directories(metadata, dataDirectories);
} catch (FSWriteError e) {
    if (e.getMessage().startsWith("Unable to create directory"))
        throw new ConfigurationException("Check ownership/permissions/read-only fs for: " + e.getMessage(), e);
    throw e;
}

Prevention

When it happens

Trigger: Startup or table creation while the parent data directory is missing, or the filesystem is read-only, or the cassandra user lacks write permission on the parent; also when the path exists but creation race-fails.

Common situations: Wrong ownership/permissions after running Cassandra once as root (dirs owned by root, service later runs as cassandra); read-only mounts (container images, snapshot restores); SELinux/AppArmor denials; full filesystems; data_file_directories pointing at non-existent, uncreatable paths.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

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