memtable_cleanup_threshold has been deprecated and should be

Error message

memtable_cleanup_threshold has been deprecated and should be removed from cassandra.yaml

What it means

A deprecation warning logged when memtable_cleanup_threshold is explicitly set in cassandra.yaml. The setting was removed in favor of memtable heap/off-heap space thresholds; Cassandra ignores the explicit value except for legacy bounds checks and tells the operator to delete it from the YAML. Startup continues.

Source

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

            throw new ConfigurationException("saved_caches_directory must not be the same as the hints_directory", false);

        initializeBackgroundWriteDiskAccessMode();

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Remove the memtable_cleanup_threshold line from cassandra.yaml and restart.
If tuning is needed, use memtable_space (heap) / memtable_offheap_space instead of the deprecated threshold.

Example fix

// cassandra.yaml before
memtable_cleanup_threshold: 0.25
// after (line removed; use modern option if tuning is needed)
# memtable_cleanup_threshold removed - deprecated
memtable_space: 2048MiB

Defensive patterns

Strategy: validation

Validate before calling

// grep the yaml before rollout
if (yamlConfig.containsKey("memtable_cleanup_threshold")) {
    throw new IllegalStateException("Remove deprecated memtable_cleanup_threshold from cassandra.yaml");
}

Prevention

Diff cassandra.yaml against the current version's conf/cassandra.yaml template before upgrades
Remove settings as they are deprecated rather than leaving them for later
Run config linting in CI for Cassandra yaml files

When it happens

Trigger: Starting a node with memtable_cleanup_threshold present in cassandra.yaml; applySimpleConfig detects the non-null value during applyAll/toolInitialization.

Common situations: Upgrading from older Cassandra versions (pre-3.x era configs carried forward); copied yaml templates from old clusters; merged config files retaining removed keys.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

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