apache/cassandra · error · ConfigurationException

memtable_flush_writers must be at least 1, but was ${conf.me

Error message

memtable_flush_writers must be at least 1, but was ${conf.memtable_flush_writers}

What it means

DatabaseDescriptor.applySimpleConfig throws this ConfigurationException when the configured memtable_flush_writers value is below 1. Cassandra auto-defaults a value of 0 based on the number of data directories, but any explicitly negative or sub-1 value is rejected because Cassandra needs at least one thread to flush memtables to SSTables.

Source

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

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

        if (conf.accord.journal_directory.equals(conf.hints_directory))
            throw new ConfigurationException("hints_directory must not be the same as the accord.journal_directory", false);
        if (conf.accord.journal_directory.equals(conf.saved_caches_directory))
            throw new ConfigurationException("saved_caches_directory must not be the same as the accord.journal_directory", false);

        if (conf.hints_directory.equals(conf.saved_caches_directory))
            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)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set memtable_flush_writers to a positive integer in cassandra.yaml (e.g. 2).
2. Remove the setting entirely to let Cassandra derive a default from the number of data_file_directories.
3. Clamp computed values in config-generation scripts to at least 1 before writing cassandra.yaml.

Example fix

// before (cassandra.yaml)
memtable_flush_writers: -1
// after
memtable_flush_writers: 2

int writers = cfg.memtable_flush_writers;
if (writers < 1)
    throw new IllegalArgumentException("memtable_flush_writers must be >= 1, was " + writers);
// 0 is allowed upstream (auto-defaulted), but safest to set an explicit positive value

boolean validFlushWriters(int v) { return v >= 1; }

try { DatabaseDescriptor.applyAll(cfg); } catch (ConfigurationException e) { logger.error("Invalid memtable_flush_writers: {}", e.getMessage()); System.exit(1); }

When it happens

Trigger: Set memtable_flush_writers to a negative number (e.g. -1) in cassandra.yaml and start the node; validation happens in applySimpleConfig after the ==0 auto-default, during toolInitialization/applyAll.

Common situations: Hand-tuning to reduce memory footprint with an invalid 0 or negative value; templating bugs where a computed value evaluated to a negative number; stale docs recommending 0 to disable flushing.

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

• Missing value for commitlog_sync_group_window.
• Missing value for commitlog_sync_period.
• concurrent_reads must be at least 2, but was ${conf.concurre
• concurrent_writes must be at least 2, but was ${conf.concurr
• accord.working_set_size option was set incorrectly to '<valu

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