apache/cassandra · error · ConfigurationException

Invalid caching sub-options %s: only '%s' and '%s' are allow

Error message

Invalid caching sub-options %s: only '%s' and '%s' are allowed

What it means

CachingParams.fromMap() parses the 'caching' table option map. After extracting the recognized sub-options ('keys' and 'rows_per_partition'), any leftover entries cause a ConfigurationException listing the offending keys, because caching accepts only those two sub-options.

Source

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

    {
        return rowsPerPartitionToCache;
    }

    public static CachingParams fromMap(Map<String, String> map)
    {
        Map<String, String> copy = new HashMap<>(map);

        String keys = copy.remove(Option.KEYS.toString());
        boolean cacheKeys = keys != null && keysFromString(keys);

        String rows = copy.remove(Option.ROWS_PER_PARTITION.toString());
        int rowsPerPartitionToCache = rows == null
                                    ? 0
                                    : rowsPerPartitionFromString(rows);

        if (!copy.isEmpty())
        {
            throw new ConfigurationException(format("Invalid caching sub-options %s: only '%s' and '%s' are allowed",
                                                    copy.keySet(),
                                                    Option.KEYS,
                                                    Option.ROWS_PER_PARTITION));
        }

        return new CachingParams(cacheKeys, rowsPerPartitionToCache);
    }

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

    private static boolean keysFromString(String value)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use only 'keys' and 'rows_per_partition' keys in the caching map
2. Replace misspelled keys (e.g. 'rows' -> 'rows_per_partition')
3. Use the shorthand form caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'} exactly

Example fix

// before
caching = {'enabled': true}
// after
caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}

java.util.Set<String> allowed = java.util.Set.of("keys", "rows_per_partition");
if (!allowed.containsAll(cachingMap.keySet())) throw new IllegalArgumentException("Unknown caching keys: " + cachingMap.keySet());

try { session.execute(ddl); } catch (InvalidQueryException e) { if (e.getMessage().contains("Invalid caching sub-options")) { /* strip unknown keys and retry */ } else throw e; }

When it happens

Trigger: CREATE/ALTER TABLE with caching = {'enabled': true} or {'all': ...} or any key other than 'keys'/'rows_per_partition', e.g. caching = {'keys': 'ALL', 'rows': 'NONE'} ('rows' instead of 'rows_per_partition').

Common situations: Migrating configs from older Cassandra versions or translating from other systems; misspelling 'rows_per_partition'; assuming an 'enabled' toggle exists in the modern map-style syntax.

Related errors

• MapType takes exactly 2 type parameters
• Invalid value %s for '%s' repair sub-option - must be an int
• Invalid value '%s' for caching sub-option '%s': only '%s' an
• Invalid value '%s' for caching sub-option '%s': only '%s', '
• Invalid value %s for '%s' compaction sub-option - must be an

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