A repair_session_space of {} mebibytes is likely to cause he

Q: What causes "A repair_session_space of {} mebibytes is likely to cause heap pressure" in apache/cassandra?

Reduce repair_session_space to at most ~25% of the JVM max heap (a common safe choice is maxMemory/16, the default)

Error message

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

What it means

repair_session_space bounds the total memory usable by concurrent repair sessions. DatabaseDescriptor warns when the configured value exceeds one quarter of the JVM max heap (maxMemory / 4 mebibytes), since committing that much heap to Merkle trees can cause GC pressure or OOM during large repairs. Values < 1 MiB are rejected outright with a ConfigurationException.

Source

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

        {
            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)
        {
            throw new ConfigurationException(String.format("native_transport_max_frame_size must be positive value < %dB, but was %dB",
                                                           Integer.MAX_VALUE,
                                                           valueInBytes),
                                             false);
        }

        if (conf.column_index_size != null)
            checkValidForByteConversion(conf.column_index_size, "column_index_size");
        checkValidForByteConversion(conf.column_index_cache_size, "column_index_cache_size");
        checkValidForByteConversion(conf.batch_size_warn_threshold, "batch_size_warn_threshold");

        // if data dirs, commitlog dir, or saved caches dir are set in cassandra.yaml, use that.  Otherwise,

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Reduce repair_session_space to at most ~25% of the JVM max heap (a common safe choice is maxMemory/16, the default)
Increase -Xmx / container memory if genuinely more repair memory is needed
Rely on the default (maxMemory/16) by removing the explicit setting

Example fix

# before (heap 8 GiB)
cassandra.yaml:
  repair_session_space: 4096MiB
# after
cassandra.yaml:
  repair_session_space: 512MiB

Defensive patterns

Strategy: validation

Validate before calling

long maxHeapMiB = Runtime.getRuntime().maxMemory() / (1024 * 1024);
if (config.repair_session_space != null && config.repair_session_space.toMebibytes() > maxHeapMiB / 4) {
    logger.warn("repair_session_space {} exceeds 25% of heap ({} MiB); reduce it", config.repair_session_space, maxHeapMiB);
}

Try / catch

try { DatabaseDescriptor.applySimpleConfig(conf); } catch (ConfigurationException e) { /* < 1 MiB rejected here */ }

Prevention

Keep repair_session_space at or below maxMemory/16 (the default)
Re-check the value whenever JVM heap or container limits change
Avoid copying large-node yaml to small nodes without resizing heap-derived settings

When it happens

Trigger: cassandra.yaml sets repair_session_space to a value whose mebibyte amount is greater than Runtime.maxMemory() / (4 * 1048576); applySimpleConfig logs the heap-pressure warning.

Common situations: Operators raising repair_session_space on heaps that were later shrunk (e.g. container memory limits reduced), or copying configs from larger nodes to smaller ones.

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

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