{"record":{"id":"ebd96257965c5531","repo":"apache/cassandra","slug":"hints-directory-must-be-specified","errorCode":null,"errorMessage":"hints_directory must be specified","messagePattern":"hints_directory must be specified","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":2426,"sourceCode":"            if (conf.data_file_directories.length == 0)\n                throw new ConfigurationException(\"At least one DataFileDirectory must be specified\", false);\n\n            for (String dataFileDirectory : conf.data_file_directories)\n                FileUtils.createDirectory(dataFileDirectory);\n\n            if (conf.local_system_data_file_directory != null)\n                FileUtils.createDirectory(conf.local_system_data_file_directory);\n\n            if (conf.commitlog_directory == null)\n                throw new ConfigurationException(\"commitlog_directory must be specified\", false);\n            FileUtils.createDirectory(conf.commitlog_directory);\n\n            if (conf.accord.journal_directory == null)\n                throw new ConfigurationException(\"accord.journal_directory must be specified\", false);\n            FileUtils.createDirectory(conf.accord.journal_directory);\n\n            if (conf.hints_directory == null)\n                throw new ConfigurationException(\"hints_directory must be specified\", false);\n            FileUtils.createDirectory(conf.hints_directory);\n\n            if (conf.saved_caches_directory == null)\n                throw new ConfigurationException(\"saved_caches_directory must be specified\", false);\n            FileUtils.createDirectory(conf.saved_caches_directory);\n\n            if (conf.cdc_enabled)\n            {\n                if (conf.cdc_raw_directory == null)\n                    throw new ConfigurationException(\"cdc_raw_directory must be specified\", false);\n                FileUtils.createDirectory(conf.cdc_raw_directory);\n            }\n\n            boolean created = maybeCreateHeapDumpPath();\n            if (!created && conf.dump_heap_on_uncaught_exception)\n            {\n                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\"));\n                conf.dump_heap_on_uncaught_exception = false;","sourceCodeStart":2408,"sourceCodeEnd":2444,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L2408-L2444","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before (cassandra.yaml)\n# hints_directory not set\n// after\nhints_directory: /var/lib/cassandra/hints","handlingStrategy":"validation","validationCode":"if (conf.hints_directory == null)\n    throw new IllegalArgumentException(\"hints_directory is required\");","typeGuard":null,"tryCatchPattern":"try { DatabaseDescriptor.daemonInitialization(); }\ncatch (ConfigurationException e) {\n    if (e.getMessage().equals(\"hints_directory must be specified\"))\n        fixYamlAndRestart();\n}","preventionTips":["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"],"tags":["configuration","hints","cassandra-yaml"],"backgroundTag":"missing-required-config-field","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}