apache/cassandra · warning

repair_session_max_tree_depth of {} > 20 could lead to exces

Error message

repair_session_max_tree_depth of {} > 20 could lead to excessive memory usage

What it means

When repair_session_max_tree_depth is set above 20 in cassandra.yaml, DatabaseDescriptor logs a warning that the deeper Merkle tree depth can lead to excessive memory usage during repair. The value is accepted, but each extra level multiplies the number of tree nodes (and thus memory) needed per repair session range.

Source

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

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

        long valueInBytes = conf.native_transport_max_frame_size.toBytes();
        if (valueInBytes < 0 || valueInBytes > Integer.MAX_VALUE - 1)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Lower repair_session_max_tree_depth to <= 20
2. Prefer tuning repair_session_space to bound repair memory instead
3. Remove the deprecated property entirely and use version defaults (depth falls back to 20)

Example fix

// before
repair_session_max_tree_depth: 28
// after
repair_session_max_tree_depth: 20   # or remove; default is 20

if (config.repair_session_max_tree_depth != null && config.repair_session_max_tree_depth > 20) {
    logger.warn("depth > 20 risks excessive memory; keep <= 20 or tune repair_session_space instead");
}

try { DatabaseDescriptor.applySimpleConfig(conf); } catch (ConfigurationException e) { /* only < 10 throws; > 20 is just a warn */ }

When it happens

Trigger: cassandra.yaml sets repair_session_max_tree_depth to a value > 20; applySimpleConfig validates and warns after passing the >= 10 check.

Common situations: Operators aggressively increasing repair granularity to resolve large repair differences or streaming mismatches, without accounting for heap cost.

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

• A repair_session_space of {} mebibytes is likely to cause he
• repair_session_space must be > 0, but was ${conf.repair_sess
• repair_session_max_tree_depth has been deprecated and should
• A repair_session_space of {} is likely to cause heap pressur
• Invalid data storage: ${value}. It shouldn't be more than ${

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