apache/cassandra · critical · ConfigurationException

data_file_directories must not contain empty entry

Error message

data_file_directories must not contain empty entry

What it means

During startup, DatabaseDescriptor iterates conf.data_file_directories and rejects any null entry with a ConfigurationException, because data directories are created and used later for storing SSTables. A null/empty entry means a malformed directory list that cannot be safely resolved.

Source

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

            logger.info("cdc_enabled is true. Starting casssandra node with Change-Data-Capture enabled.");
        }

        if (conf.saved_caches_directory == null)
        {
            conf.saved_caches_directory = storagedirFor("saved_caches");
        }
        if (conf.data_file_directories == null || conf.data_file_directories.length == 0)
        {
            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)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Remove the empty/null entry from data_file_directories in cassandra.yaml
  2. Fix the template/config-generation so the directory list contains only non-empty absolute paths
  3. Validate the rendered cassandra.yaml (e.g. with a YAML linter) before deployment

Example fix

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

Strategy: validation

Validate before calling

List<String> dirs = (List<String>) yaml.get("data_file_directories");
if (dirs == null || dirs.isEmpty())
    throw new IllegalArgumentException("data_file_directories is required");
for (String d : dirs)
    if (d == null || d.isBlank())
        throw new IllegalArgumentException("data_file_directories must not contain empty entries");

Type guard

static boolean validDataDirs(List<String> dirs) {
    return dirs != null && !dirs.isEmpty() && dirs.stream().allMatch(d -> d != null && !d.isBlank());
}

Try / catch

try {
    DatabaseDescriptor.toolInitialization();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("data_file_directories"))
        throw new StartupConfigError("fix empty entries in data_file_directories", e);
    throw e;
}

Prevention

When it happens

Trigger: cassandra.yaml data_file_directories list containing a null/empty element (e.g. 'data_file_directories: [/var/lib/cassandra/data, ,]' or a YAML structure yielding null items); validated in applySimpleConfig at every startup.

Common situations: YAML formatting mistakes (trailing commas, mis-indented list items); templating tools (Ansible/Helm) rendering an empty variable into the list; env-var substitution producing empty strings in generated configs.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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