apache/cassandra · critical · ConfigurationException

At least one DataFileDirectory must be specified

Error message

At least one DataFileDirectory must be specified

What it means

During createAllDirectories, DatabaseDescriptor requires conf.data_file_directories to be non-empty before creating each directory; a missing value means Cassandra has nowhere to place SSTables, so it throws this ConfigurationException (non-logged variant). This is one of the mandatory-directory checks at the start of node initialization.

Solutions

  1. Set data_file_directories in cassandra.yaml to one or more existing/writable paths
  2. Ensure the cassandra.config system property points at the intended yaml file
  3. In programmatic use, set the data file locations on the Config before createAllDirectories

Example fix

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

Strategy: try-catch

Validate before calling

if (conf.data_file_directories == null || conf.data_file_directories.length == 0)
    throw new IllegalArgumentException("data_file_directories must be set in cassandra.yaml");

Try / catch

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) {
    if (e.getMessage().contains("DataFileDirectory"))
        abortStartupWithConfigHint();
}

Prevention

When it happens

Trigger: Starting Cassandra with a cassandra.yaml that omits data_file_directories entirely, or a programmatic Config object (tests/Dtest) where the data file locations array is empty when createAllDirectories is called.

Common situations: Empty or malformed cassandra.yaml (properties stripped, wrong config file loaded via cassandra.config); programmatic setup that initializes DatabaseDescriptor before setting data_file_directories; overwritten cassandra.yaml during upgrade.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

    {
        return conf.max_value_size.toBytes();
    }

    public static void setMaxValueSize(int maxValueSizeInBytes)
    {
        // the below division is safe as this setter is used only in tests with values that won't lead to precision loss
        conf.max_value_size = new DataStorageSpec.IntMebibytesBound((maxValueSizeInBytes / (1024L * 1024)), MEBIBYTES);
    }

    /**
     * Creates all storage-related directories.
     */
    public static void createAllDirectories()
    {
        try
        {
            if (conf.data_file_directories.length == 0)
                throw new ConfigurationException("At least one DataFileDirectory must be specified", false);

            for (String dataFileDirectory : conf.data_file_directories)
                FileUtils.createDirectory(dataFileDirectory);

            if (conf.local_system_data_file_directory != null)
                FileUtils.createDirectory(conf.local_system_data_file_directory);

            if (conf.commitlog_directory == null)
                throw new ConfigurationException("commitlog_directory must be specified", false);
            FileUtils.createDirectory(conf.commitlog_directory);

            if (conf.accord.journal_directory == null)
                throw new ConfigurationException("accord.journal_directory must be specified", false);
            FileUtils.createDirectory(conf.accord.journal_directory);

            if (conf.hints_directory == null)
                throw new ConfigurationException("hints_directory must be specified", false);
            FileUtils.createDirectory(conf.hints_directory);

View on GitHub (pinned to 88fd0f6a0e)