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

Thrown during custom index (SAI/custom Indexer) option validation when the indexer class's static validateOptions(Map) method returns a set of option keys it does not recognize. Cassandra rejects the index creation/alter statement because the supplied properties are not part of the indexer's accepted option contract. Raised as org.apache.cassandra.exceptions.ConfigurationException.

Source

Thrown at src/java/org/apache/cassandra/schema/IndexMetadata.java:186

        try
        {
            Map<String, String> filteredOptions = Maps.filterKeys(options, key -> !key.equals(IndexTarget.CUSTOM_INDEX_OPTION_NAME));

            if (filteredOptions.isEmpty())
                return;

            Map<?, ?> unknownOptions;
            try
            {
                unknownOptions = (Map) indexerClass.getMethod("validateOptions", Map.class, TableMetadata.class).invoke(null, filteredOptions, table);
            }
            catch (NoSuchMethodException e)
            {
                unknownOptions = (Map) indexerClass.getMethod("validateOptions", Map.class).invoke(null, filteredOptions);
            }

            if (!unknownOptions.isEmpty())
                throw new ConfigurationException(String.format("Properties specified %s are not understood by %s", unknownOptions.keySet(), indexerClass.getSimpleName()));
        }
        catch (NoSuchMethodException e)
        {
            logger.info("Indexer {} does not have a static validateOptions method. Validation ignored",
                        indexerClass.getName());
        }
        catch (InvocationTargetException e)
        {
            if (e.getTargetException() instanceof InvalidRequestException)
                throw (InvalidRequestException) e.getTargetException();
            if (e.getTargetException() instanceof ConfigurationException)
                throw (ConfigurationException) e.getTargetException();
            throw new ConfigurationException("Failed to validate custom indexer options: " + options);
        }
        catch (ConfigurationException e)
        {
            throw e;
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check the exact option key names against the indexer class's validateOptions implementation and documentation; fix typos and casing.
2. Remove options not supported by the target indexer class.
3. Verify the correct indexer class is specified in USING — options may belong to a different indexer.
4. If you wrote the indexer, ensure validateOptions removes consumed keys from the returned map; only truly unknown keys should remain.

Example fix

// before
CREATE CUSTOM INDEX my_idx ON ks.tbl (col) USING 'com.example.MyIndexer' WITH OPTIONS = {'class_name':'com.example.MyIndexer', 'case_sensetive': true};
// after
CREATE CUSTOM INDEX my_idx ON ks.tbl (col) USING 'com.example.MyIndexer' WITH OPTIONS = {'class_name':'com.example.MyIndexer', 'case_sensitive': true};

Set<String> known = indexerValidateOptionsKeys; // consult the indexer's validateOptions docs/source
for (String k : options.keySet()) if (!known.contains(k) && !k.equals("class_name")) throw new IllegalArgumentException("Unknown indexer option: " + k);

try { schema.createIndex(withOptions); } catch (ConfigurationException e) { if (e.getMessage().contains("are not understood by")) logUnknownOptionsAndFix(); else throw e; }

When it happens

Trigger: CREATE CUSTOM INDEX ... USING 'com.example.MyIndexer' WITH OPTIONS {...} (or ALTER) where one or more keys in OPTIONS are not consumed by MyIndexer.validateOptions; validateCustomIndexOptions filters out known keys then invokes the indexer's static validateOptions reflectively and the returned unknownOptions map is non-empty.

Common situations: Typos in option names, copying options between different custom indexers with different option sets, upgrading an indexer plugin whose option names changed, mixing SAI-specific options with a third-party indexer that doesn't support them.

Related errors

• Fan factor cannot be lower than 2 in %s
• %s %s is not acceptable, size must be at least %s
• Invalid configuration, %s should be greater than or equal to
• Invalid configuration, %s (%s) should be less than 70%% of t
• Unable to parse targets for index %s (%s)

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