apache/cassandra · error · ConfigurationException

Cannot set repair_session_space to < 1 mebibyte

Error message

Cannot set repair_session_space to < 1 mebibyte

What it means

Cassandra throws this ConfigurationException when setRepairSessionSpaceInMiB is called with a size below 1 MiB. repair_session_space bounds the total memory used by repair Merkle trees per repair session; values under 1 MiB cannot be honored.

Source

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

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set the value to at least 1 MiB
2. If heap pressure is the concern, reduce concurrent repair validators instead of the per-session space
3. Check cassandra.yaml repair_session_space uses MiB units (e.g. 16MiB)

Example fix

// before
DatabaseDescriptor.setRepairSessionSpaceInMiB(0);
// after
DatabaseDescriptor.setRepairSessionSpaceInMiB(16);

if (sizeInMiB < 1) throw new IllegalArgumentException("repair_session_space must be at least 1 MiB");

try {
    DatabaseDescriptor.setRepairSessionSpaceInMiB(sizeInMiB);
} catch (ConfigurationException e) {
    logger.warn("repair_session_space must be >= 1 MiB; keeping current value", e);
}

When it happens

Trigger: Calling DatabaseDescriptor.setRepairSessionSpaceInMiB(0) or any value < 1, via JMX config updates or programmatic configuration.

Common situations: Operators on memory-constrained nodes shrink repair_session_space to nearly zero to relieve heap pressure; unit confusion where someone enters bytes or intends a fraction of a MiB.

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

• repair_session_space must be > 0, but was ${conf.repair_sess
• repair_session_max_tree_depth should not be < 10, but was ${
• To set concurrent_validations > concurrent_compactors, set t
• Cannot set repair_session_max_tree_depth to which is < 10, d
• Value must be >= 0 and <= 1 for repair_disk_headroom_reject_

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