{"record":{"id":"343107f6816220f0","repo":"apache/cassandra","slug":"properties-specified-s-are-not-understood-by-s-343107","errorCode":null,"errorMessage":"Properties specified %s are not understood by %s","messagePattern":"Properties specified (.+?) are not understood by (.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/schema/IndexMetadata.java","lineNumber":186,"sourceCode":"        try\n        {\n            Map<String, String> filteredOptions = Maps.filterKeys(options, key -> !key.equals(IndexTarget.CUSTOM_INDEX_OPTION_NAME));\n\n            if (filteredOptions.isEmpty())\n                return;\n\n            Map<?, ?> unknownOptions;\n            try\n            {\n                unknownOptions = (Map) indexerClass.getMethod(\"validateOptions\", Map.class, TableMetadata.class).invoke(null, filteredOptions, table);\n            }\n            catch (NoSuchMethodException e)\n            {\n                unknownOptions = (Map) indexerClass.getMethod(\"validateOptions\", Map.class).invoke(null, filteredOptions);\n            }\n\n            if (!unknownOptions.isEmpty())\n                throw new ConfigurationException(String.format(\"Properties specified %s are not understood by %s\", unknownOptions.keySet(), indexerClass.getSimpleName()));\n        }\n        catch (NoSuchMethodException e)\n        {\n            logger.info(\"Indexer {} does not have a static validateOptions method. Validation ignored\",\n                        indexerClass.getName());\n        }\n        catch (InvocationTargetException e)\n        {\n            if (e.getTargetException() instanceof InvalidRequestException)\n                throw (InvalidRequestException) e.getTargetException();\n            if (e.getTargetException() instanceof ConfigurationException)\n                throw (ConfigurationException) e.getTargetException();\n            throw new ConfigurationException(\"Failed to validate custom indexer options: \" + options);\n        }\n        catch (ConfigurationException e)\n        {\n            throw e;\n        }","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/schema/IndexMetadata.java#L168-L204","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the exact option key names against the indexer class's validateOptions implementation and documentation; fix typos and casing.","Remove options not supported by the target indexer class.","Verify the correct indexer class is specified in USING — options may belong to a different indexer.","If you wrote the indexer, ensure validateOptions removes consumed keys from the returned map; only truly unknown keys should remain."],"exampleFix":"// before\nCREATE CUSTOM INDEX my_idx ON ks.tbl (col) USING 'com.example.MyIndexer' WITH OPTIONS = {'class_name':'com.example.MyIndexer', 'case_sensetive': true};\n// after\nCREATE CUSTOM INDEX my_idx ON ks.tbl (col) USING 'com.example.MyIndexer' WITH OPTIONS = {'class_name':'com.example.MyIndexer', 'case_sensitive': true};","handlingStrategy":"validation","validationCode":"Set<String> known = indexerValidateOptionsKeys; // consult the indexer's validateOptions docs/source\nfor (String k : options.keySet()) if (!known.contains(k) && !k.equals(\"class_name\")) throw new IllegalArgumentException(\"Unknown indexer option: \" + k);","typeGuard":null,"tryCatchPattern":"try { schema.createIndex(withOptions); } catch (ConfigurationException e) { if (e.getMessage().contains(\"are not understood by\")) logUnknownOptionsAndFix(); else throw e; }","preventionTips":["Keep a canonical list of each indexer's supported options next to your DDL scripts.","Option names are case-sensitive — verify spelling against the indexer's validateOptions implementation.","Test index creation against a dev cluster before production DDL.","When switching indexer classes, audit the OPTIONS map for stale keys."],"tags":["cassandra","index","configuration","validation"],"backgroundTag":"unsupported-config-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}