apache/cassandra · error · ConfigurationException

hints_directory must not be the same as the accord.journal_d

Error message

hints_directory must not be the same as the accord.journal_directory

What it means

DatabaseDescriptor.applySimpleConfig throws this ConfigurationException when the Accord journal directory equals the hints directory. Both are durable write locations that must remain on distinct configured paths so their I/O and space usage do not interfere.

Source

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

            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);

            long freeBytes = tryGetSpace(conf.local_system_data_file_directory, FileStore::getUnallocatedSpace);

            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)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set accord.journal_directory to a different path than hints_directory in cassandra.yaml.
If sharing a device, use distinct subdirectories.
Re-review cassandra.yaml for duplicate directory values after any Accord-related edits.

Example fix

// before (cassandra.yaml)
accord:
  journal_directory: /data/misc
hints_directory: /data/misc
// after
accord:
  journal_directory: /data/misc/accord_journal
hints_directory: /data/misc/hints

Defensive patterns

Strategy: validation

Validate before calling

if (cfg.accord != null && cfg.accord.journal_directory != null && cfg.accord.journal_directory.equals(cfg.hints_directory))
    throw new IllegalArgumentException("accord.journal_directory must differ from hints_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

Assign the Accord journal a path distinct from hints at initial setup
Run the uniqueness lint on every config change
Avoid reusing an existing auxiliary directory key for new journal settings

When it happens

Trigger: Set accord.journal_directory equal to hints_directory in cassandra.yaml and start the node; validation happens in applySimpleConfig (toolInitialization/applyAll).

Common situations: Fresh Accord setups where the journal was pointed at an existing hints volume; template configs with a single 'misc' volume path reused for several directory keys.

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/088eb609d6540eee. Report an issue: GitHub.