apache/cassandra · error · ConfigurationException

Cannot set repair_session_max_tree_depth to which is < 10, d

Error message

Cannot set repair_session_max_tree_depth to which is < 10, doing nothing

What it means

Cassandra throws this ConfigurationException when setRepairSessionMaxTreeDepth is called with a depth below 10. The Merkle-tree depth for repair sessions controls tree granularity; values under 10 are not permitted, while values over 20 only produce a memory-usage warning.

Source

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

    public static long getMemtableOffheapSpaceInMiB()
    {
        return conf.memtable_offheap_space.toMebibytes();
    }

    public static Config.MemtableAllocationType getMemtableAllocationType()
    {
        return conf.memtable_allocation_type;
    }

    public static int getRepairSessionMaxTreeDepth()
    {
        return conf.repair_session_max_tree_depth;
    }

    public static void setRepairSessionMaxTreeDepth(int depth)
    {
        if (depth < 10)
            throw new ConfigurationException("Cannot set repair_session_max_tree_depth to " + depth +
                                             " which is < 10, doing nothing");
        else if (depth > 20)
            logger.warn("repair_session_max_tree_depth of " + depth + " > 20 could lead to excessive memory usage");

        conf.repair_session_max_tree_depth = depth;
    }

    public static int getRepairSessionSpaceInMiB()
    {
        return conf.repair_session_space.toMebibytes();
    }

    public static void setRepairSessionSpaceInMiB(int sizeInMiB)
    {
        if (sizeInMiB < 1)
            throw new ConfigurationException("Cannot set repair_session_space to " + sizeInMiB +
                                             " < 1 mebibyte");
        else if (sizeInMiB > (int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)))

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set the depth to at least 10
If smaller trees are needed for memory reasons, reduce parallel repair sessions (repair_session_space) instead
Verify the value in cassandra.yaml for repair_session_max_tree_depth

Example fix

// before
DatabaseDescriptor.setRepairSessionMaxTreeDepth(8);
// after
DatabaseDescriptor.setRepairSessionMaxTreeDepth(12);

Defensive patterns

Strategy: validation

Validate before calling

if (depth < 10 || depth > 20) throw new IllegalArgumentException("repair_session_max_tree_depth should be between 10 and 20, got: " + depth);

Try / catch

try {
    DatabaseDescriptor.setRepairSessionMaxTreeDepth(depth);
} catch (ConfigurationException e) {
    logger.warn("Invalid repair_session_max_tree_depth; using default", e);
}

Prevention

Keep the depth in the 10-20 range (above 20 only warns about memory)
Tune repair memory via repair_session_space instead of lowering depth below 10
Double-check numeric config edits for transposition errors

When it happens

Trigger: Calling DatabaseDescriptor.setRepairSessionMaxTreeDepth(depth) with depth < 10, e.g. via JMX nodetool-side config updates or startup validation of repair_session_max_tree_depth.

Common situations: Operators tuning repair performance lower the depth to reduce memory, going below the enforced minimum of 10; mistakes transposing values (e.g. entering 1 instead of 16).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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