apache/cassandra · error · ConfigurationException

Invalid value '%s' for caching sub-option '%s': only '%s' an

Error message

Invalid value '%s' for caching sub-option '%s': only '%s' and '%s' are allowed

What it means

The 'keys' caching sub-option only accepts the literal strings 'ALL' or 'NONE' (case-insensitive). keysFromString throws MarshalException-style ConfigurationException for any other value while parsing the option during CREATE/ALTER TABLE.

Source

Thrown at src/java/org/apache/cassandra/schema/CachingParams.java:130

    }

    public Map<String, String> asMap()
    {
        return ImmutableMap.of(Option.KEYS.toString(),
                               keysAsString(),
                               Option.ROWS_PER_PARTITION.toString(),
                               rowsPerPartitionAsString());
    }

    private static boolean keysFromString(String value)
    {
        if (value.equalsIgnoreCase(ALL))
            return true;

        if (value.equalsIgnoreCase(NONE))
            return false;

        throw new ConfigurationException(format("Invalid value '%s' for caching sub-option '%s': only '%s' and '%s' are allowed",
                                                value,
                                                Option.KEYS,
                                                ALL,
                                                NONE));
    }

    String keysAsString()
    {
        return cacheKeys ? ALL : NONE;
    }

    private static int rowsPerPartitionFromString(String value)
    {
        if (value.equalsIgnoreCase(ALL))
            return Integer.MAX_VALUE;

        if (value.equalsIgnoreCase(NONE))
            return 0;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Use 'ALL' or 'NONE' (case-insensitive) for the 'keys' sub-option
Remove the 'keys' sub-option to inherit the default

Example fix

// before
caching = {'keys': 'true'}
// after
caching = {'keys': 'ALL'}

Defensive patterns

Strategy: validation

Validate before calling

String v = cachingMap.get("keys");
if (v != null && !(v.equalsIgnoreCase("ALL") || v.equalsIgnoreCase("NONE"))) throw new IllegalArgumentException("keys must be ALL or NONE");

Type guard

boolean isValidKeysOption(String v) { return "ALL".equalsIgnoreCase(v) || "NONE".equalsIgnoreCase(v); }

Try / catch

try { session.execute(ddl); } catch (InvalidQueryException e) { if (e.getMessage().contains("caching sub-option 'keys'")) { /* normalize to ALL/NONE and retry */ } else throw e; }

Prevention

Normalize booleans/old syntax to ALL/NONE before generating DDL
Use case-insensitive checks on your side, Cassandra's check is case-insensitive
Keep a single constants list of legal caching values in schema tooling

When it happens

Trigger: CREATE TABLE ... WITH caching = {'keys': 'all_keys'} or {'keys': 'true'} — any value other than ALL/NONE passed to the keys sub-option.

Common situations: Developers coming from older Cassandra (<3.0) where caching was {'keys': 'ALL', 'rows_per_partition': 'NONE'} vs boolean-style or from KeyCache terminology, typing values like 'KEYS_ONLY' or 'TRUE'.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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