apache/cassandra · error · ConfigurationException

repair_session_space must be > 0, but was ${conf.repair_sess

Error message

repair_session_space must be > 0, but was ${conf.repair_session_space}

What it means

repair_session_space caps the total memory Merkle trees in active repair sessions may use. DatabaseDescriptor throws ConfigurationException at startup if the configured value is less than 1 MiB. When unset, a default of max(1, maxMemory/16MiB) MiB is computed; a warning (not an error) is emitted above maxMemory/4MiB.

Source

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

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set repair_session_space to at least 1MiB in cassandra.yaml (e.g. repair_session_space: 512MiB)
2. Remove the option to let Cassandra compute a default from heap size (maxMemory/16MiB)
3. Verify the DataStorageSpec unit suffix parses to the intended mebibyte value

Example fix

// before (cassandra.yaml)
repair_session_space: 0
// after (cassandra.yaml)
repair_session_space: 512MiB

Object v = yaml.get("repair_session_space");
if (v != null) {
    DataStorageSpec.IntMebibytesBound b = DataStorageSpec.IntMebibytesBound.parse(v.toString());
    if (b.toMebibytes() < 1)
        throw new IllegalArgumentException("repair_session_space must be >= 1MiB, got " + b);
}

try {
    DatabaseDescriptor.daemonInitialization();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("repair_session_space"))
        throw new StartupConfigError("repair_session_space must be at least 1MiB", e);
    throw e;
}

When it happens

Trigger: Setting repair_session_space to 0 or a sub-1MiB value (e.g. '512KiB') in cassandra.yaml; applySimpleConfig validates toMebibytes() < 1 during toolInitialization/applyAll.

Common situations: Typo in unit suffix causing tiny parsed value; attempts to 'disable' repair memory by setting it to 0; copy-pasted configs from smaller nodes.

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

• repair_session_max_tree_depth should not be < 10, but was ${
• Cannot set repair_session_space to < 1 mebibyte
• the local data center must be part of the repair; requested
• Bloom filter size is > 16GB, reduce the bloom_filter_fp_chan
• repair_session_max_tree_depth of {} > 20 could lead to exces

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