apache/cassandra · error · ConfigurationException

key_cache_size option was set incorrectly to '<value>', supp

Error message

key_cache_size option was set incorrectly to '<value>', supported values are <integer> >= 0.

What it means

key_cache_size must be a non-negative integer (MiB) or 'auto'. When the value cannot be parsed in applySimpleConfig, ConfigurationException is thrown with the configured value and the expected format.

Source

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

                                             + (conf.prepared_statements_cache_size != null ? conf.prepared_statements_cache_size.toString() : null) + "', supported values are <integer> >= 0.", false);
        }

        try
        {
            // if key_cache_size option was set to "auto" then size of the cache should be "min(5% of Heap (in MiB), 100MiB)
            keyCacheSizeInMiB = (conf.key_cache_size == null)
                                ? Math.min(Math.max(1, (int) (Runtime.getRuntime().totalMemory() * 0.05 / 1024 / 1024)), 100)
                                : conf.key_cache_size.toMebibytes();

            if (keyCacheSizeInMiB < 0)
                throw new NumberFormatException(); // to escape duplicating error message

            // we need this assignment for the Settings Virtual Table - CASSANDRA-17734
            conf.key_cache_size = new DataStorageSpec.LongMebibytesBound(keyCacheSizeInMiB);
        }
        catch (NumberFormatException e)
        {
            throw new ConfigurationException("key_cache_size option was set incorrectly to '"
                                             + (conf.key_cache_size != null ? conf.key_cache_size.toString() : null) + "', supported values are <integer> >= 0.", false);
        }

        try
        {
            // if counter_cache_size option was set to "auto" then size of the cache should be "min(2.5% of Heap (in MiB), 50MiB)
            counterCacheSizeInMiB = (conf.counter_cache_size == null)
                                    ? Math.min(Math.max(1, (int) (Runtime.getRuntime().totalMemory() * 0.025 / 1024 / 1024)), 50)
                                    : conf.counter_cache_size.toMebibytes();

            if (counterCacheSizeInMiB < 0)
                throw new NumberFormatException(); // to escape duplicating error message
        }
        catch (NumberFormatException e)
        {
            throw new ConfigurationException("counter_cache_size option was set incorrectly to '"
                                             + (conf.counter_cache_size != null ? conf.counter_cache_size.toString() : null) + "', supported values are <integer> >= 0.", false);
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Set key_cache_size to a plain non-negative integer of MiB, e.g. 100
  2. Use 'auto' for min(5% of heap, 100MiB)
  3. Remove the key to accept the default
  4. Restart the node

Example fix

// before (cassandra.yaml)
key_cache_size: 100MB
// after
key_cache_size: 100
// or
key_cache_size: auto
Defensive patterns

Strategy: validation

Validate before calling

String v = yaml.get("key_cache_size");
if (v != null && !v.equals("auto") && Long.parseLong(v) < 0) throw new IllegalArgumentException(v);

Try / catch

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) { LOG.fatal(e.getMessage()); System.exit(1); }

Prevention

When it happens

Trigger: Node startup with key_cache_size in cassandra.yaml that is non-numeric, negative, or uses a unit suffix.

Common situations: Unit suffix like '100MB'; negative value intending unlimited; YAML indentation error making the value land on the wrong key and type.

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

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