apache/cassandra · error · ConfigurationException

memtable_cleanup_threshold must be >= 0.01, but was ${conf.m

Error message

memtable_cleanup_threshold must be >= 0.01, but was ${conf.memtable_cleanup_threshold}

What it means

Cassandra requires memtable_cleanup_threshold to be at least 0.01. During startup DatabaseDescriptor.applySimpleConfig validates the value loaded from cassandra.yaml and throws ConfigurationException if it falls below this lower bound, because a threshold this small would trigger memtable cleanup far too aggressively and destabilize the node.

Source

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

        if (conf.memtable_flush_writers == 0)
        {
            conf.memtable_flush_writers = conf.data_file_directories.length == 1 ? 2 : 1;
        }

        if (conf.memtable_flush_writers < 1)
            throw new ConfigurationException("memtable_flush_writers must be at least 1, but was " + conf.memtable_flush_writers, false);

        if (conf.memtable_cleanup_threshold == null)
        {
            conf.memtable_cleanup_threshold = (float) (1.0 / (1 + conf.memtable_flush_writers));
        }
        else
        {
            logger.warn("memtable_cleanup_threshold has been deprecated and should be removed from cassandra.yaml");
        }

        if (conf.memtable_cleanup_threshold < 0.01f)
            throw new ConfigurationException("memtable_cleanup_threshold must be >= 0.01, but was " + conf.memtable_cleanup_threshold, false);
        if (conf.memtable_cleanup_threshold > 0.99f)
            throw new ConfigurationException("memtable_cleanup_threshold must be <= 0.99, but was " + conf.memtable_cleanup_threshold, false);
        if (conf.memtable_cleanup_threshold < 0.1f)
            logger.warn("memtable_cleanup_threshold is set very low [{}], which may cause performance degradation", conf.memtable_cleanup_threshold);

        if (conf.concurrent_compactors == null)
            conf.concurrent_compactors = Math.min(8, Math.max(2, Math.min(FBUtilities.getAvailableProcessors(), conf.data_file_directories.length)));

        if (conf.concurrent_compactors <= 0)
            throw new ConfigurationException("concurrent_compactors should be strictly greater than 0, but was " + conf.concurrent_compactors, false);

        applyConcurrentValidations(conf);
        applyRepairCommandPoolSize(conf);
        applyThresholdsValidations(conf);

        if (conf.concurrent_materialized_view_builders <= 0)
            throw new ConfigurationException("concurrent_materialized_view_builders should be strictly greater than 0, but was " + conf.concurrent_materialized_view_builders, false);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Edit cassandra.yaml and set memtable_cleanup_threshold to a value in [0.01, 0.99] (typically 0.1 or leave it unset to accept defaults)
2. Remove the memtable_cleanup_threshold key entirely — it is deprecated and the default is used
3. If the value is templated, fix the template/default so it emits a valid float >= 0.01
4. Restart the node after correcting the config

Example fix

// before (cassandra.yaml)
memtable_cleanup_threshold: 0
// after
delete the line, or:
memtable_cleanup_threshold: 0.1

// Pre-startup config check
if (conf.memtable_cleanup_threshold < 0.01f || conf.memtable_cleanup_threshold > 0.99f)
    throw new IllegalArgumentException("memtable_cleanup_threshold must be in [0.01, 0.99]: " + conf.memtable_cleanup_threshold);

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) { LOG.fatal("Bad cassandra.yaml: " + e.getMessage()); System.exit(1); }

When it happens

Trigger: Node startup (DatabaseDescriptor.toolInitialization / applyAll -> applySimpleConfig) with cassandra.yaml containing memtable_cleanup_threshold: 0.0, a negative value, or any value < 0.01.

Common situations: Hand-edited cassandra.yaml with a typo or mis-scaled value (e.g. 0 instead of 0.1); automated config templating that substitutes an unset variable producing 0; copying config from an old cluster with a bad value.

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

• memtable_cleanup_threshold must be <= 0.99, but was ${conf.m
• native_transport_max_message_size must not exceed native_tra
• Invalid configuration for cms_commit_retry_strategy.
• Set listen_address OR listen_interface, not both
• Only {} free in the system data volume. Consider adding more

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