What causes "saved_caches_directory must be specified" in apache/cassandra?

Add saved_caches_directory to cassandra.yaml (e.g. /var/lib/cassandra/saved_caches)

apache/cassandra · critical · ConfigurationException

saved_caches_directory must be specified

Error message

saved_caches_directory must be specified

What it means

createAllDirectories validates that conf.saved_caches_directory is configured before creating it; saved caches (key/save cache persistence) need a directory, and an unset value throws this ConfigurationException during node startup.

Solutions

Add saved_caches_directory to cassandra.yaml (e.g. /var/lib/cassandra/saved_caches)
Verify the exact key spelling (saved_caches_directory) in the yaml
In programmatic setups, set Config.saved_caches_directory before DatabaseDescriptor initialization

Example fix

// before (cassandra.yaml)
# saved_caches_directory not set
// after
saved_caches_directory: /var/lib/cassandra/saved_caches

Defensive patterns

Strategy: validation

Validate before calling

if (conf.saved_caches_directory == null)
    throw new IllegalArgumentException("saved_caches_directory is required");

Try / catch

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) {
    if (e.getMessage().equals("saved_caches_directory must be specified"))
        fixYamlAndRestart();
}

Prevention

Spell the key exactly as saved_caches_directory
Include it in the same template block as data/commitlog/hints directories
Run config validation (dry init) before rollout

When it happens

Trigger: cassandra.yaml lacks saved_caches_directory (or it is null in a programmatic Config) when createAllDirectories runs; typically right after the hints_directory check passes.

Common situations: Over-aggressive config pruning for container images; config copied from a minimal/older setup; typo such as saved_cache_directory (singular) that leaves the real key unset.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

                FileUtils.createDirectory(dataFileDirectory);

            if (conf.local_system_data_file_directory != null)
                FileUtils.createDirectory(conf.local_system_data_file_directory);

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

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

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

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

            if (conf.cdc_enabled)
            {
                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)
        {

View on GitHub (pinned to 88fd0f6a0e)