apache/cassandra · warning

A repair_session_space of {} is likely to cause heap pressur

Error message

A repair_session_space of {} is likely to cause heap pressure.

What it means

repair_session_space caps the total memory repair sessions (validation compactions / Merkle trees) may use. If the configured value exceeds roughly max heap / 4, DatabaseDescriptor logs this warning because such a large repair allocation is likely to pressure the JVM heap and cause GC issues or OOM during repair.

Source

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

                                             " 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)))
            logger.warn("A repair_session_space of " + conf.repair_session_space +
                        " is likely to cause heap pressure.");

        conf.repair_session_space = new DataStorageSpec.IntMebibytesBound(sizeInMiB);
    }

    public static int getConcurrentMerkleTreeRequests()
    {
        return conf.concurrent_merkle_tree_requests;
    }

    public static void setConcurrentMerkleTreeRequests(int value)
    {
        conf.concurrent_merkle_tree_requests = value;
    }

    public static int getPaxosRepairParallelism()
    {
        return conf.paxos_repair_parallelism;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Lower repair_session_space to <= 25% of max heap (compute with java's maxMemory/4MiB)
2. Increase JVM heap if repair throughput requires more session memory and keep repair_session_space below the new 25% bound
3. Accept the warning only with explicit heap monitoring during repairs

Example fix

// before (32GB heap)
repair_session_space: 16384MiB
// after
repair_session_space: 8192MiB

int maxMiB = (int)(Runtime.getRuntime().maxMemory() / (4 * 1048576));
if (cfg.repair_session_space_miB > maxMiB) throw new IllegalArgumentException("repair_session_space must be <= " + maxMiB + "MiB");

try { DatabaseDescriptor.setRepairSessionSpaceInMiB(mib); } catch (ConfigurationException e) { /* < 1MiB rejected */ }

When it happens

Trigger: Calling DatabaseDescriptor.setRepairSessionSpaceInMiB(sizeInMiB) where sizeInMiB > maxMemory/(4*1048576); values < 1 throw a ConfigurationException instead. Also produced by setting repair_session_space in cassandra.yaml to more than 25% of heap.

Common situations: Operators on large-heap nodes bumping repair_session_space to speed repairs, or a shrunk heap after a restart leaving a previously fine value now above the heap/4 threshold.

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 of {} > 20 could lead to exces
• repair_session_max_tree_depth should not be < 10, but was ${
• Cannot set repair_session_space to < 1 mebibyte

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