apache/cassandra · error · ConfigurationException

Properties specified %s are not understood by %s

Error message

Properties specified %s are not understood by %s

What it means

CompactionParams.validate() reflectively invokes the compaction strategy class's static validateOptions(Map) method and throws ConfigurationException when the strategy reports any unrecognized option keys. It means the compaction map contains sub-options the chosen strategy class does not understand.

Source

Thrown at src/java/org/apache/cassandra/schema/CompactionParams.java:200

        String threshold = options.get(Option.MAX_THRESHOLD.toString());
        return threshold == null
             ? DEFAULT_MAX_THRESHOLD
             : Integer.parseInt(threshold);
    }

    public TombstoneOption tombstoneOption()
    {
        return tombstoneOption;
    }

    public void validate()
    {
        try
        {
            Map<?, ?> unknownOptions = (Map) klass.getMethod("validateOptions", Map.class).invoke(null, options);
            if (!unknownOptions.isEmpty())
            {
                throw new ConfigurationException(format("Properties specified %s are not understood by %s",
                                                        unknownOptions.keySet(),
                                                        klass.getSimpleName()));
            }
        }
        catch (NoSuchMethodException e)
        {
            logger.warn("Compaction strategy {} does not have a static validateOptions method. Validation ignored",
                        klass.getName());
        }
        catch (InvocationTargetException e)
        {
            if (e.getTargetException() instanceof ConfigurationException)
                throw (ConfigurationException) e.getTargetException();

            Throwable cause = e.getCause() == null
                            ? e
                            : e.getCause();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove or correct the keys listed in the message's 'Properties specified [...]' output.
2. Consult the compaction strategy class (e.g. SizeTieredCompactionStrategy.validateOptions) for the exact supported sub-option names.
3. After a version upgrade, migrate options to their new names (e.g. check CHANGES.txt for renamed compaction options).

Example fix

// before
ALTER TABLE t WITH compaction = {'class':'TimeWindowCompactionStrategy','min_threshold':'4'};
// after
ALTER TABLE t WITH compaction = {'class':'TimeWindowCompactionStrategy','compaction_window_size':'1','compaction_window_unit':'DAYS'};

Map<String, String> unknown = compactionClass.getMethod("validateOptions", Map.class).invoke(null, opts);
if (!unknown.isEmpty()) throw new IllegalArgumentException("Unknown options: " + unknown.keySet());

try { applyCompaction(opts); } catch (ConfigurationException e) {
    logger.warn("Rejecting compaction options: {}", e.getMessage());
    // fall back to strategy defaults
}

When it happens

Trigger: ALTER TABLE ... WITH compaction = {'class':'XStrategy', 'unknown_option': 'v'} where XStrategy.validateOptions() returns the unknown key; e.g. using TWCS-only options (compaction_window_unit) with LCS, or legacy option names after a Cassandra upgrade.

Common situations: Copy-pasting compaction settings between strategy classes; upgrading Cassandra and using renamed/removed sub-options; typos in option keys like 'min_threshold' vs class-specific names.

Related errors

• %s.validateOptions() threw an error: %s %s
• concurrent_compactors should be strictly greater than 0, but
• Could not set new local compaction strategy: <cause message>
• %s is not a parsable int (base10) for %s
• %s must not be negative, but was %d

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