apache/cassandra · critical · 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 commitlog_directory

What it means

When conf.local_system_data_file_directory is set, it must differ from commitlog_directory (and from accord journal, saved_caches, hints directories). applySimpleConfig throws ConfigurationException if local_system_data_file_directory equals the commitlog_directory, refusing startup so local system-ks data and the write-ahead log never share a directory.

Source

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

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

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set local_system_data_file_directory to its own unique path (e.g. /var/lib/cassandra/local_system)
Remove local_system_data_file_directory if per-keyspace separation is not needed (it is optional)
Uniqueness-check all directory settings (data dirs, commitlog, hints, saved_caches, accord journal, local system) before rollout

Example fix

# before (cassandra.yaml)
commitlog_directory: /var/lib/cassandra/commitlog
local_system_data_file_directory: /var/lib/cassandra/commitlog
# after (cassandra.yaml)
commitlog_directory: /var/lib/cassandra/commitlog
local_system_data_file_directory: /var/lib/cassandra/local_system

Defensive patterns

Strategy: validation

Validate before calling

String local = (String) yaml.get("local_system_data_file_directory");
String commitlog = (String) yaml.get("commitlog_directory");
if (local != null && local.equals(commitlog))
    throw new IllegalArgumentException("local_system_data_file_directory must differ from commitlog_directory");
// also check accord.journal_directory, saved_caches_directory, hints_directory

Try / catch

try {
    DatabaseDescriptor.toolInitialization();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("local_system_data_file_directory"))
        throw new StartupConfigError("local system directory overlaps commitlog/other directories", e);
    throw e;
}

Prevention

Assign local_system_data_file_directory a path not used by any other directory
Only set the option when local-system keyspace separation is actually required
Enforce pairwise-distinct directory checks in deployment tooling

When it happens

Trigger: Setting local_system_data_file_directory in cassandra.yaml to the same path as commitlog_directory (or accord.journal_directory / saved_caches_directory / hints_directory); validated during startup when the local system directory is non-null.

Common situations: Operators carving out a separate local-system location but accidentally reusing the commitlog path; single-disk setups where all optional directories collapse to one path; automated config generation with a shared base path.

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/889a3e29954d6144. Report an issue: GitHub.