apache/cassandra · error · IllegalStateException

; unable to start server

Error message

; unable to start server

What it means

When daemon init fails with FSWriteError (typically a filesystem failure creating required directories), DatabaseDescriptor rethrows it as IllegalStateException with the filesystem error cause message followed by '; unable to start server'.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:2453

                if (conf.cdc_raw_directory == null)
                    throw new ConfigurationException("cdc_raw_directory must be specified", false);
                FileUtils.createDirectory(conf.cdc_raw_directory);
            }

            boolean created = maybeCreateHeapDumpPath();
            if (!created && conf.dump_heap_on_uncaught_exception)
            {
                logger.error(String.format("cassandra.yaml:dump_heap_on_uncaught_exception is enabled but unable to create heap dump path %s. Disabling.", conf.heap_dump_path != null ? conf.heap_dump_path : "null"));
                conf.dump_heap_on_uncaught_exception = false;
            }
        }
        catch (ConfigurationException e)
        {
            throw new IllegalArgumentException("Bad configuration; unable to start server: " + e.getMessage());
        }
        catch (FSWriteError e)
        {
            throw new IllegalStateException(e.getCause().getMessage() + "; unable to start server", e);
        }
    }

    public static IPartitioner getPartitioner()
    {
        return partitioner;
    }

    public static String getPartitionerName()
    {
        return partitionerName;
    }

    /* For tests ONLY, don't use otherwise or all hell will break loose. Tests should restore value at the end. */
    public static IPartitioner setPartitionerUnsafe(IPartitioner newPartitioner)
    {
        IPartitioner old = setOnlyPartitionerUnsafe(newPartitioner);
        StorageService.instance.valueFactory = new VersionedValue.VersionedValueFactory(partitioner);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check the cause message before '; unable to start server' to identify the failing path
2. Create the directory and chown/chmod it to the Cassandra user
3. Verify disk is writable and not full (df/mount)
4. Correct path settings in cassandra.yaml

Example fix

// before (yaml)
data_file_directories: [/data/cassandra/data]  # mount does not exist
// after
data_file_directories: [/var/lib/cassandra/data]

java.nio.file.Path dir = java.nio.file.Paths.get(dataDir);
if (!java.nio.file.Files.isDirectory(dir) || !java.nio.file.Files.isWritable(dir))
    throw new IllegalStateException("Data directory not writable: " + dir);

try { DatabaseDescriptor.daemonInitialize(); }
catch (IllegalStateException e) {
    String fsProblem = e.getMessage().replace("; unable to start server", "");
    logger.error("Filesystem issue: {}", fsProblem);
}

When it happens

Trigger: Data/data_file_directories, commitlog, saved_caches, cdc_raw or heap dump path cannot be created on disk: bad path, permissions, disk full, read-only filesystem.

Common situations: Running as a user without write permission on data directories; mount not present in containers; SELinux/AppArmor blocking writes; disk full.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Unable check disk space in '%s'. Perhaps the Cassandra user
• Unable to create directory " + dir
• ERR_WRONG_DISK_STATE
• Directory {} doesn't exist
• Dictionary file %s is not readable.

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