apache/cassandra · critical · ConfigurationException

saved_caches_directory must not be the same as any data_file

Error message

saved_caches_directory must not be the same as any data_file_directories

What it means

saved_caches_directory holds persisted key/table caches and must not overlap any data_file_directories. DatabaseDescriptor.applySimpleConfig throws ConfigurationException when a data directory string-equals conf.saved_caches_directory, refusing startup to keep cache files separate from SSTable data.

Source

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

            conf.data_file_directories = new String[]{ storagedir("data_file_directories") + File.pathSeparator() + "data" };
        }

        long dataFreeBytes = 0;
        /* data file and commit log directories. they get created later, when they're needed. */
        for (String datadir : conf.data_file_directories)
        {
            if (datadir == null)
                throw new ConfigurationException("data_file_directories must not contain empty entry", false);
            if (datadir.equals(conf.local_system_data_file_directory))
                throw new ConfigurationException("local_system_data_file_directory must not be the same as any data_file_directories", false);
            if (datadir.equals(conf.commitlog_directory))
                throw new ConfigurationException("commitlog_directory must not be the same as any data_file_directories", false);
            if (datadir.equals(conf.accord.journal_directory))
                throw new ConfigurationException("accord.journal_directory must not be the same as any data_file_directories", false);
            if (datadir.equals(conf.hints_directory))
                throw new ConfigurationException("hints_directory must not be the same as any data_file_directories", false);
            if (datadir.equals(conf.saved_caches_directory))
                throw new ConfigurationException("saved_caches_directory must not be the same as any data_file_directories", false);

            dataFreeBytes = saturatedSum(dataFreeBytes, tryGetSpace(datadir, FileStore::getUnallocatedSpace));
        }
        if (dataFreeBytes < 64 * ONE_GIB) // 64 GB
            logger.warn("Only {} free across all data volumes. Consider adding more capacity to your cluster or removing obsolete snapshots",
                        FBUtilities.prettyPrintMemory(dataFreeBytes));

        if (conf.local_system_data_file_directory != null)
        {
            if (conf.local_system_data_file_directory.equals(conf.commitlog_directory))
                throw new ConfigurationException("local_system_data_file_directory must not be the same as the commitlog_directory", false);
            if (conf.local_system_data_file_directory.equals(conf.accord.journal_directory))
                throw new ConfigurationException("local_system_data_file_directory must not be the same as the accord.journal_directory", false);
            if (conf.local_system_data_file_directory.equals(conf.saved_caches_directory))
                throw new ConfigurationException("local_system_data_file_directory must not be the same as the saved_caches_directory", false);
            if (conf.local_system_data_file_directory.equals(conf.hints_directory))
                throw new ConfigurationException("local_system_data_file_directory must not be the same as the hints_directory", false);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Set saved_caches_directory to a distinct path (e.g. /var/lib/cassandra/saved_caches)
  2. Use sibling subdirectories for each function if everything shares one volume
  3. Audit generated cassandra.yaml so each directory setting is unique

Example fix

# before (cassandra.yaml)
data_file_directories:
  - /var/lib/cassandra/data
saved_caches_directory: /var/lib/cassandra/data
# after (cassandra.yaml)
data_file_directories:
  - /var/lib/cassandra/data
saved_caches_directory: /var/lib/cassandra/saved_caches
Defensive patterns

Strategy: validation

Validate before calling

String caches = (String) yaml.get("saved_caches_directory");
List<String> dirs = (List<String>) yaml.get("data_file_directories");
if (caches != null && dirs != null && dirs.contains(caches))
    throw new IllegalArgumentException("saved_caches_directory must differ from all data_file_directories");

Try / catch

try {
    DatabaseDescriptor.toolInitialization();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("saved_caches_directory"))
        throw new StartupConfigError("saved_caches_directory overlaps a data directory", e);
    throw e;
}

Prevention

When it happens

Trigger: Setting saved_caches_directory in cassandra.yaml to the same path as any data_file_directories entry; checked in the same data-directory loop during applySimpleConfig at startup.

Common situations: Minimal single-path deployments where every *directory option was pointed at the same location; templated configs rendering identical paths; legacy configs from a single-directory install.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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