apache/cassandra · error · ConfigurationException

local_system_data_file_directory must not be the same as the

Error message

local_system_data_file_directory must not be the same as the accord.journal_directory

What it means

At startup Cassandra validates that all dedicated directories point to distinct filesystem paths. This ConfigurationException is thrown by DatabaseDescriptor.applySimpleConfig when the configured local_system_data_file_directory is identical to the accord.journal_directory, because both subsystems need independent write bandwidth and disk-space accounting; sharing a volume can corrupt capacity assumptions and starve Accord durable storage.

Source

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

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

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Edit cassandra.yaml so local_system_data_file_directory and accord.journal_directory are different paths (e.g. /var/lib/cassandra/local_system vs /var/lib/cassandra/accord_journal).
  2. If directories must share a filesystem, keep the configured path strings distinct (distinct subdirectories) — the check compares path equality, not device identity.
  3. If local_system_data_file_directory is unnecessary, remove/comment it so this validation block is skipped entirely.

Example fix

// before (cassandra.yaml)
local_system_data_file_directory: /data/cassandra
accord:
  journal_directory: /data/cassandra
// after
local_system_data_file_directory: /data/cassandra/local_system
accord:
  journal_directory: /data/cassandra/accord_journal
Defensive patterns

Strategy: validation

Validate before calling

// before startup
String local = cfg.local_system_data_file_directory;
String journal = cfg.accord != null ? cfg.accord.journal_directory : null;
if (local != null && local.equals(journal))
    throw new IllegalArgumentException("local_system_data_file_directory must differ from accord.journal_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("Invalid directory configuration: {}", e.getMessage()); System.exit(1); }

Prevention

When it happens

Trigger: Set cassandra.yaml local_system_data_file_directory to the exact same path string as accord.journal_directory, then start the node (or apply the config via ConfigHelper.applyAll / toolInitialization during config loading).

Common situations: Copy-pasting cassandra.yaml where several *_directory settings were left pointing to the same mount point; operators consolidating directories onto a single SSD; scripts that set both dirs to a common prefix like /var/lib/cassandra without distinguishing subpaths.

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/6e8779b4ebdb6d88. Report an issue: GitHub.