What causes "hints_directory must be specified" in apache/cassandra?

Add hints_directory to cassandra.yaml (e.g. /var/lib/cassandra/hints)

apache/cassandra · critical · ConfigurationException

hints_directory must be specified

Error message

hints_directory must be specified

What it means

createAllDirectories checks that conf.hints_directory is set before creating it; hints storage is required for hinted handoff, so an unset value throws this ConfigurationException during startup validation.

Solutions

Add hints_directory to cassandra.yaml (e.g. /var/lib/cassandra/hints)
Ensure the path is on writable storage for the cassandra user
In test/programmatic setups, set Config.hints_directory before initialization

Example fix

// before (cassandra.yaml)
# hints_directory not set
// after
hints_directory: /var/lib/cassandra/hints

Defensive patterns

Strategy: validation

Validate before calling

if (conf.hints_directory == null)
    throw new IllegalArgumentException("hints_directory is required");

Try / catch

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) {
    if (e.getMessage().equals("hints_directory must be specified"))
        fixYamlAndRestart();
}

Prevention

Keep hints_directory in every environment's yaml template
Add a startup config linter asserting the full set of mandatory directories
Diff deployed configs against the shipped default cassandra.yaml after upgrades

When it happens

Trigger: cassandra.yaml omits hints_directory, or a programmatic Config leaves it null when createAllDirectories is invoked; also occurs if a config-management tool rendered the template without this key.

Common situations: Hand-edited or template-generated cassandra.yaml missing the hints_directory line; drift after upgrading where the old config lacked the (now mandatory) key; containers built with trimmed config files.

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

Appendix: source

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

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

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

            if (conf.cdc_enabled)
            {
                if (conf.cdc_raw_directory == null)
                    throw new ConfigurationException("cdc_raw_directory must be specified", false);
                FileUtils.createDirectory(conf.cdc_raw_directory);
            }

            boolean created = maybeCreateHeapDumpPath();
            if (!created && conf.dump_heap_on_uncaught_exception)
            {
                logger.error(String.format("cassandra.yaml:dump_heap_on_uncaught_exception is enabled but unable to create heap dump path %s. Disabling.", conf.heap_dump_path != null ? conf.heap_dump_path : "null"));
                conf.dump_heap_on_uncaught_exception = false;

View on GitHub (pinned to 88fd0f6a0e)