apache/cassandra · error · ConfigurationException

saved_caches_directory must not be the same as the…

Error message

saved_caches_directory must not be the same as the hints_directory

What it means

DatabaseDescriptor.applySimpleConfig throws this ConfigurationException when the hints directory equals the saved caches directory. Cassandra requires hints and saved caches to occupy distinct configured paths so hint replay data and cache snapshots never share the same directory.

Solutions

  1. Change hints_directory or saved_caches_directory in cassandra.yaml to a distinct path.
  2. Use separate subdirectories under one mount if only a single disk is available.
  3. Verify pairwise uniqueness of all directory settings before restarting the node.

Example fix

// before (cassandra.yaml)
hints_directory: /data/aux
saved_caches_directory: /data/aux
// after
hints_directory: /data/aux/hints
saved_caches_directory: /data/aux/saved_caches
Defensive patterns

Strategy: validation

Validate before calling

if (cfg.hints_directory != null && cfg.hints_directory.equals(cfg.saved_caches_directory))
    throw new IllegalArgumentException("hints_directory must differ from saved_caches_directory");

Type guard

boolean dirsDistinct(String a, String b) { return a == null || b == null || !new File(a).getAbsolutePath().equals(new File(b).getAbsolutePath()); }

Try / catch

try { DatabaseDescriptor.applyAll(cfg); } catch (ConfigurationException e) { logger.error("Directory collision: {}", e.getMessage()); System.exit(1); }

Prevention

When it happens

Trigger: Set hints_directory equal to saved_caches_directory in cassandra.yaml and start the node; check executes during applySimpleConfig before further startup validation (e.g. memtable_flush_writers checks).

Common situations: Operators merging all auxiliary directories into one path on small volumes; copy-pasted cassandra.yaml entries that accidentally matched.

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/2cb2951e9ba91406. Report an issue: GitHub.

Appendix: source

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

            if (freeBytes < ONE_GIB)
                logger.warn("Only {} free in the system data volume. Consider adding more capacity or removing obsolete snapshots",
                            FBUtilities.prettyPrintMemory(freeBytes));
        }

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

        if (conf.accord.journal_directory.equals(conf.hints_directory))
            throw new ConfigurationException("hints_directory must not be the same as the accord.journal_directory", false);
        if (conf.accord.journal_directory.equals(conf.saved_caches_directory))
            throw new ConfigurationException("saved_caches_directory must not be the same as the accord.journal_directory", false);

        if (conf.hints_directory.equals(conf.saved_caches_directory))
            throw new ConfigurationException("saved_caches_directory must not be the same as the hints_directory", false);

        initializeBackgroundWriteDiskAccessMode();

        if (conf.memtable_flush_writers == 0)
        {
            conf.memtable_flush_writers = conf.data_file_directories.length == 1 ? 2 : 1;
        }

        if (conf.memtable_flush_writers < 1)
            throw new ConfigurationException("memtable_flush_writers must be at least 1, but was " + conf.memtable_flush_writers, false);

        if (conf.memtable_cleanup_threshold == null)
        {
            conf.memtable_cleanup_threshold = (float) (1.0 / (1 + conf.memtable_flush_writers));
        }
        else
        {
            logger.warn("memtable_cleanup_threshold has been deprecated and should be removed from cassandra.yaml");

View on GitHub (pinned to 88fd0f6a0e)