apache/cassandra · error · ConfigurationException

memtable_heap_space must be positive, but was ${conf.memtabl

Error message

memtable_heap_space must be positive, but was ${conf.memtable_heap_space}

What it means

memtable_heap_space_in_mb is the global on-heap memtable flush threshold; when unset it defaults to max heap / 4 MiB units. applySimpleConfig rejects a resolved value of 0 MiB, because a zero threshold would make cleanup-based memtable management either trigger constantly or never, both unsafe. The ConfigurationException fires when the explicit or derived value rounds to 0.

Source

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

            throw new ConfigurationException("concurrent_counter_writes must be at least 2, but was " + conf.concurrent_counter_writes, false);

        if (conf.networking_cache_size == null)
            conf.networking_cache_size = new DataStorageSpec.IntMebibytesBound(Math.min(128, (int) (Runtime.getRuntime().maxMemory() / (16 * 1048576))));

        if (conf.file_cache_size == null)
            conf.file_cache_size = new DataStorageSpec.IntMebibytesBound(Math.min(512, (int) (Runtime.getRuntime().maxMemory() / (4 * 1048576))));

        // round down for SSDs and round up for spinning disks
        if (conf.file_cache_round_up == null)
            conf.file_cache_round_up = conf.disk_optimization_strategy == Config.DiskOptimizationStrategy.spinning;

        if (conf.memtable_offheap_space == null)
            conf.memtable_offheap_space = new DataStorageSpec.IntMebibytesBound((int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)));
        // for the moment, we default to twice as much on-heap space as off-heap, as heap overhead is very large
        if (conf.memtable_heap_space == null)
            conf.memtable_heap_space = new DataStorageSpec.IntMebibytesBound((int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)));
        if (conf.memtable_heap_space.toMebibytes() == 0)
            throw new ConfigurationException("memtable_heap_space must be positive, but was " + conf.memtable_heap_space, false);
        logger.info("Global memtable on-heap threshold is enabled at {}", conf.memtable_heap_space);
        if (conf.memtable_offheap_space.toMebibytes() == 0)
            logger.info("Global memtable off-heap threshold is disabled, HeapAllocator will be used instead");
        else
            logger.info("Global memtable off-heap threshold is enabled at {}", conf.memtable_offheap_space);

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set `memtable_heap_space_in_mb` (e.g. 256+) explicitly in cassandra.yaml, or enlarge the heap so the default is >= 1 MiB.
2. Remove the override so the default (max heap / 4) applies.
3. Fix unit suffix mistakes: the value is parsed as a DataStorageSpec.IntMebibytesBound — ensure suffixes like '256MiB' are written correctly and not '0'.

Example fix

// before (cassandra.yaml)
memtable_heap_space_in_mb: 0
// after (cassandra.yaml)
memtable_heap_space_in_mb: 1024

// Java, before toolInitialization()
long heapBytes = Runtime.getRuntime().maxMemory();
var raw = Config.getRawConfig();
long mb = raw != null && raw.memtable_heap_space != null
        ? raw.memtable_heap_space.toMebibytes()
        : heapBytes / (4L * 1048576L);
if (mb <= 0)
    throw new IllegalArgumentException("memtable_heap_space resolves to 0 MiB; increase heap or set it explicitly");

When it happens

Trigger: Setting `memtable_heap_space_in_mb: 0` (or a sub-megabyte value that truncates to 0, e.g. 512KB) in cassandra.yaml, or running with a tiny -Xmx such that the derived default maxHeap/4 falls below 1 MiB, during DatabaseDescriptor.toolInitialization/applyAll.

Common situations: Embedded Cassandra usage (tests, tools like sstable utilities) with a very small heap; operators attempting to 'disable' memtable pressure tracking by setting 0; config calculators mis-converting bytes/KB/MB for the DataStorageSpec 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

• %s must be positive value <= %dB, but was %dB
• Invalid value of auto_snapshot_ttl: ${conf.auto_snapshot_ttl
• Missing value for commitlog_sync_group_window.
• Missing value for commitlog_sync_period.
• concurrent_reads must be at least 2, but was ${conf.concurre

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