What causes "prepared_statements_cache_size option was set incorrectly to ' ', supported values are >= 0." in apache/cassandra?

Set prepared_statements_cache_size to a plain non-negative integer of MiB, e.g. 256

apache/cassandra · error · ConfigurationException

prepared_statements_cache_size option was set incorrectly to

Error message

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

What it means

prepared_statements_cache_size must parse as a non-negative integer (MiB) or the special value 'auto'. If parsing to preparedStatementsCacheSizeInMiB fails (NumberFormatException), applySimpleConfig wraps it as ConfigurationException showing the offending value.

Source

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

        if (conf.num_tokens != null && conf.num_tokens > MAX_NUM_TOKENS)
            throw new ConfigurationException(String.format("A maximum number of %d tokens per node is supported", MAX_NUM_TOKENS), false);

        try
        {
            // if prepared_statements_cache_size option was set to "auto" then size of the cache should be "max(1/256 of Heap (in MiB), 10MiB)"
            preparedStatementsCacheSizeInMiB = (conf.prepared_statements_cache_size == null)
                                               ? Math.max(10, (int) (Runtime.getRuntime().maxMemory() / 1024 / 1024 / 256))
                                               : conf.prepared_statements_cache_size.toMebibytes();

            if (preparedStatementsCacheSizeInMiB == 0)
                throw new NumberFormatException(); // to escape duplicating error message

            // we need this assignment for the Settings virtual table - CASSANDRA-17734
            conf.prepared_statements_cache_size = new DataStorageSpec.LongMebibytesBound(preparedStatementsCacheSizeInMiB);
        }
        catch (NumberFormatException e)
        {
            throw new ConfigurationException("prepared_statements_cache_size option was set incorrectly to '"
                                             + (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)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set prepared_statements_cache_size to a plain non-negative integer of MiB, e.g. 256
Use the literal value auto to size the cache automatically (max(1/256 of heap, 10MiB))
Remove the key to accept the auto default
Restart the node

Example fix

// before (cassandra.yaml)
prepared_statements_cache_size: 10MB
// after
prepared_statements_cache_size: 256
// or
prepared_statements_cache_size: auto

Defensive patterns

Strategy: validation

Validate before calling

// value must be a bare non-negative integer (MiB) or the literal 'auto'
String v = yaml.get("prepared_statements_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

Never append unit suffixes to cache size options
Use 'auto' when unsure
Keep cache sizes as integers in MiB in config templates

When it happens

Trigger: Node startup where cassandra.yaml has prepared_statements_cache_size set to a non-numeric string, a negative number, or an unparseable unit form.

Common situations: Writing '10MB' or '10 MiB' when a bare integer is expected; quoting issues in YAML; setting -1 intending 'unlimited'; locale-formatted numbers.

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/ce0e77d3b769b66f. Report an issue: GitHub.