{"record":{"id":"7afd61cb3022b15c","repo":"apache/cassandra","slug":"hints-directory-must-not-be-the-same-as-any-data-f","errorCode":null,"errorMessage":"hints_directory must not be the same as any data_file_directories","messagePattern":"hints_directory must not be the same as any data_file_directories","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":893,"sourceCode":"        if (conf.data_file_directories == null || conf.data_file_directories.length == 0)\n        {\n            conf.data_file_directories = new String[]{ storagedir(\"data_file_directories\") + File.pathSeparator() + \"data\" };\n        }\n\n        long dataFreeBytes = 0;\n        /* data file and commit log directories. they get created later, when they're needed. */\n        for (String datadir : conf.data_file_directories)\n        {\n            if (datadir == null)\n                throw new ConfigurationException(\"data_file_directories must not contain empty entry\", false);\n            if (datadir.equals(conf.local_system_data_file_directory))\n                throw new ConfigurationException(\"local_system_data_file_directory must not be the same as any data_file_directories\", false);\n            if (datadir.equals(conf.commitlog_directory))\n                throw new ConfigurationException(\"commitlog_directory must not be the same as any data_file_directories\", false);\n            if (datadir.equals(conf.accord.journal_directory))\n                throw new ConfigurationException(\"accord.journal_directory must not be the same as any data_file_directories\", false);\n            if (datadir.equals(conf.hints_directory))\n                throw new ConfigurationException(\"hints_directory must not be the same as any data_file_directories\", false);\n            if (datadir.equals(conf.saved_caches_directory))\n                throw new ConfigurationException(\"saved_caches_directory must not be the same as any data_file_directories\", false);\n\n            dataFreeBytes = saturatedSum(dataFreeBytes, tryGetSpace(datadir, FileStore::getUnallocatedSpace));\n        }\n        if (dataFreeBytes < 64 * ONE_GIB) // 64 GB\n            logger.warn(\"Only {} free across all data volumes. Consider adding more capacity to your cluster or removing obsolete snapshots\",\n                        FBUtilities.prettyPrintMemory(dataFreeBytes));\n\n        if (conf.local_system_data_file_directory != null)\n        {\n            if (conf.local_system_data_file_directory.equals(conf.commitlog_directory))\n                throw new ConfigurationException(\"local_system_data_file_directory must not be the same as the commitlog_directory\", false);\n            if (conf.local_system_data_file_directory.equals(conf.accord.journal_directory))\n                throw new ConfigurationException(\"local_system_data_file_directory must not be the same as the accord.journal_directory\", false);\n            if (conf.local_system_data_file_directory.equals(conf.saved_caches_directory))\n                throw new ConfigurationException(\"local_system_data_file_directory must not be the same as the saved_caches_directory\", false);\n            if (conf.local_system_data_file_directory.equals(conf.hints_directory))","sourceCodeStart":875,"sourceCodeEnd":911,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L875-L911","documentation":"hints_directory stores hinted handoff data and must be distinct from all data_file_directories. applySimpleConfig throws ConfigurationException if any data directory string-equals conf.hints_directory, preventing the node from starting with hints written into SSTable directories.","triggerScenarios":"Setting hints_directory in cassandra.yaml equal to any data_file_directories entry; validated during DatabaseDescriptor initialization (applySimpleConfig via toolInitialization/applyAll).","commonSituations":"Consolidated-directory deployments; config generators that assign one base path to all directory settings; operators moving hints onto the data disk without adjusting the path to a subdirectory.","solutions":["Set hints_directory to a distinct path (e.g. /var/lib/cassandra/hints)","Use a sibling subdirectory of the data volume if disk sharing is intended, never the exact data directory","Re-run config validation after any directory migration"],"exampleFix":"# before (cassandra.yaml)\ndata_file_directories:\n  - /var/lib/cassandra/data\nhints_directory: /var/lib/cassandra/data\n# after (cassandra.yaml)\ndata_file_directories:\n  - /var/lib/cassandra/data\nhints_directory: /var/lib/cassandra/hints","handlingStrategy":"validation","validationCode":"String hints = (String) yaml.get(\"hints_directory\");\nList<String> dirs = (List<String>) yaml.get(\"data_file_directories\");\nif (hints != null && dirs != null && dirs.contains(hints))\n    throw new IllegalArgumentException(\"hints_directory must differ from all data_file_directories\");","typeGuard":null,"tryCatchPattern":"try {\n    DatabaseDescriptor.toolInitialization();\n} catch (ConfigurationException e) {\n    if (e.getMessage().contains(\"hints_directory\"))\n        throw new StartupConfigError(\"hints_directory overlaps a data directory\", e);\n    throw e;\n}","preventionTips":["Keep hints in its own directory (e.g. /var/lib/cassandra/hints)","Run directory-uniqueness linting on generated configs","Re-validate after any storage layout migration"],"tags":["cassandra","configuration","directories","hints"],"backgroundTag":"conflicting-config-options","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}