{"record":{"id":"a271fb6073f3782c","repo":"apache/cassandra","slug":"repair-session-max-tree-depth-should-not-be-10","errorCode":null,"errorMessage":"repair_session_max_tree_depth should not be < 10, but was ${conf.repair_session_max_tree_depth}","messagePattern":"repair_session_max_tree_depth should not be < 10, but was (.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":766,"sourceCode":"\n        if (conf.memtable_offheap_space == null)\n            conf.memtable_offheap_space = new DataStorageSpec.IntMebibytesBound((int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)));\n        // for the moment, we default to twice as much on-heap space as off-heap, as heap overhead is very large\n        if (conf.memtable_heap_space == null)\n            conf.memtable_heap_space = new DataStorageSpec.IntMebibytesBound((int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)));\n        if (conf.memtable_heap_space.toMebibytes() == 0)\n            throw new ConfigurationException(\"memtable_heap_space must be positive, but was \" + conf.memtable_heap_space, false);\n        logger.info(\"Global memtable on-heap threshold is enabled at {}\", conf.memtable_heap_space);\n        if (conf.memtable_offheap_space.toMebibytes() == 0)\n            logger.info(\"Global memtable off-heap threshold is disabled, HeapAllocator will be used instead\");\n        else\n            logger.info(\"Global memtable off-heap threshold is enabled at {}\", conf.memtable_offheap_space);\n\n        if (conf.repair_session_max_tree_depth != null)\n        {\n            logger.warn(\"repair_session_max_tree_depth has been deprecated and should be removed from cassandra.yaml. Use repair_session_space instead\");\n            if (conf.repair_session_max_tree_depth < 10)\n                throw new ConfigurationException(\"repair_session_max_tree_depth should not be < 10, but was \" + conf.repair_session_max_tree_depth);\n            if (conf.repair_session_max_tree_depth > 20)\n                logger.warn(\"repair_session_max_tree_depth of \" + conf.repair_session_max_tree_depth + \" > 20 could lead to excessive memory usage\");\n        }\n        else\n        {\n            conf.repair_session_max_tree_depth = 20;\n        }\n\n        if (conf.repair_session_space == null)\n            conf.repair_session_space = new DataStorageSpec.IntMebibytesBound(Math.max(1, (int) (Runtime.getRuntime().maxMemory() / (16 * 1048576))));\n\n        if (conf.repair_session_space.toMebibytes() < 1)\n            throw new ConfigurationException(\"repair_session_space must be > 0, but was \" + conf.repair_session_space);\n        else if (conf.repair_session_space.toMebibytes() > (int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)))\n            logger.warn(\"A repair_session_space of \" + conf.repair_session_space + \" mebibytes is likely to cause heap pressure\");\n\n        checkForLowestAcceptedTimeouts(conf);\n","sourceCodeStart":748,"sourceCodeEnd":784,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L748-L784","documentation":"Cassandra rejects cassandra.yaml files that set repair_session_max_tree_depth below 10. This setting controls the max depth of Merkle trees used during incremental repair; trees too shallow produce too many ranges and excessive overhead. During startup configuration validation (DatabaseDescriptor.applySimpleConfig) a ConfigurationException is thrown and the node refuses to start. Note the option itself is deprecated in favor of repair_session_space.","triggerScenarios":"Setting repair_session_max_tree_depth: < 10 in cassandra.yaml (or programmatically via Config) and starting the node; applySimpleConfig is called during DatabaseDescriptor.toolInitialization/applyAll, i.e. during normal node startup.","commonSituations":"Operators tuning repair memory hand-edit cassandra.yaml with too small a value; leftover deprecated repair_session_max_tree_depth entries in upgraded clusters (a warning is logged for any presence of the key).","solutions":["Set repair_session_max_tree_depth to a value >= 10 in cassandra.yaml","Preferably remove repair_session_max_tree_depth entirely from cassandra.yaml (it is deprecated; use repair_session_space instead)","If tuning repair memory, configure repair_session_space (e.g. repair_session_space: 1024MiB) rather than tree depth"],"exampleFix":"// before (cassandra.yaml)\nrepair_session_max_tree_depth: 5\n// after (cassandra.yaml)\n# deprecated option removed; tune memory instead\nrepair_session_space: 1024MiB","handlingStrategy":"validation","validationCode":"Integer depth = (Integer) yaml.get(\"repair_session_max_tree_depth\");\nif (depth != null && depth < 10)\n    throw new IllegalArgumentException(\"repair_session_max_tree_depth must be >= 10, got \" + depth);\nif (depth != null)\n    logger.warn(\"repair_session_max_tree_depth is deprecated; use repair_session_space\");","typeGuard":null,"tryCatchPattern":"try {\n    DatabaseDescriptor.toolInitialization();\n} catch (ConfigurationException e) {\n    if (e.getMessage().contains(\"repair_session_max_tree_depth\"))\n        // fix cassandra.yaml: value >= 10 or remove the key\n        throw new StartupConfigError(\"invalid repair_session_max_tree_depth\", e);\n    throw e;\n}","preventionTips":["Never set repair_session_max_tree_depth below 10","Remove the deprecated key and use repair_session_space instead","Add config linting for cassandra.yaml in CI"],"tags":["cassandra","configuration","startup-validation","repair"],"backgroundTag":"invalid-config-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}