apache/cassandra · error · ConfigurationException

repair_session_max_tree_depth should not be < 10, but was ${

Error message

repair_session_max_tree_depth should not be < 10, but was ${conf.repair_session_max_tree_depth}

What it means

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.

Source

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

        if (conf.memtable_offheap_space == null)
            conf.memtable_offheap_space = new DataStorageSpec.IntMebibytesBound((int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)));
        // for the moment, we default to twice as much on-heap space as off-heap, as heap overhead is very large
        if (conf.memtable_heap_space == null)
            conf.memtable_heap_space = new DataStorageSpec.IntMebibytesBound((int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)));
        if (conf.memtable_heap_space.toMebibytes() == 0)
            throw new ConfigurationException("memtable_heap_space must be positive, but was " + conf.memtable_heap_space, false);
        logger.info("Global memtable on-heap threshold is enabled at {}", conf.memtable_heap_space);
        if (conf.memtable_offheap_space.toMebibytes() == 0)
            logger.info("Global memtable off-heap threshold is disabled, HeapAllocator will be used instead");
        else
            logger.info("Global memtable off-heap threshold is enabled at {}", conf.memtable_offheap_space);

        if (conf.repair_session_max_tree_depth != null)
        {
            logger.warn("repair_session_max_tree_depth has been deprecated and should be removed from cassandra.yaml. Use repair_session_space instead");
            if (conf.repair_session_max_tree_depth < 10)
                throw new ConfigurationException("repair_session_max_tree_depth should not be < 10, but was " + conf.repair_session_max_tree_depth);
            if (conf.repair_session_max_tree_depth > 20)
                logger.warn("repair_session_max_tree_depth of " + conf.repair_session_max_tree_depth + " > 20 could lead to excessive memory usage");
        }
        else
        {
            conf.repair_session_max_tree_depth = 20;
        }

        if (conf.repair_session_space == null)
            conf.repair_session_space = new DataStorageSpec.IntMebibytesBound(Math.max(1, (int) (Runtime.getRuntime().maxMemory() / (16 * 1048576))));

        if (conf.repair_session_space.toMebibytes() < 1)
            throw new ConfigurationException("repair_session_space must be > 0, but was " + conf.repair_session_space);
        else if (conf.repair_session_space.toMebibytes() > (int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)))
            logger.warn("A repair_session_space of " + conf.repair_session_space + " mebibytes is likely to cause heap pressure");

        checkForLowestAcceptedTimeouts(conf);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set repair_session_max_tree_depth to a value >= 10 in cassandra.yaml
2. Preferably remove repair_session_max_tree_depth entirely from cassandra.yaml (it is deprecated; use repair_session_space instead)
3. If tuning repair memory, configure repair_session_space (e.g. repair_session_space: 1024MiB) rather than tree depth

Example fix

// before (cassandra.yaml)
repair_session_max_tree_depth: 5
// after (cassandra.yaml)
# deprecated option removed; tune memory instead
repair_session_space: 1024MiB

Integer depth = (Integer) yaml.get("repair_session_max_tree_depth");
if (depth != null && depth < 10)
    throw new IllegalArgumentException("repair_session_max_tree_depth must be >= 10, got " + depth);
if (depth != null)
    logger.warn("repair_session_max_tree_depth is deprecated; use repair_session_space");

try {
    DatabaseDescriptor.toolInitialization();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("repair_session_max_tree_depth"))
        // fix cassandra.yaml: value >= 10 or remove the key
        throw new StartupConfigError("invalid repair_session_max_tree_depth", e);
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• repair_session_space must be > 0, but was ${conf.repair_sess
• internode_max_message_size must no exceed internode_applicat
• the local data center must be part of the repair; requested
• Write thresholds require top partitions tracking to be enabl
• Load CIDR groups cache operation not supported by %s

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