{"record":{"id":"a408e8ac82b4173e","repo":"apache/cassandra","slug":"sparse-mode-doesn-t-support-analyzers","errorCode":null,"errorMessage":"SPARSE mode doesn't support analyzers.","messagePattern":"SPARSE mode doesn't support analyzers\\.","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sasi/SASIIndex.java","lineNumber":182,"sourceCode":"        if (target == null)\n            throw new ConfigurationException(\"failed to retrieve target column for: \" + targetColumn);\n\n        if (target.left.isComplex())\n            throw new ConfigurationException(\"complex columns are not yet supported by SASI\");\n\n        if (target.left.isPartitionKey())\n            throw new ConfigurationException(\"partition key columns are not yet supported by SASI\");\n\n        IndexMode.validateAnalyzer(options, target.left);\n\n        IndexMode mode = IndexMode.getMode(target.left, options);\n        if (mode.mode == Mode.SPARSE)\n        {\n            if (mode.isLiteral)\n                throw new ConfigurationException(\"SPARSE mode is only supported on non-literal columns.\");\n\n            if (mode.isAnalyzed)\n                throw new ConfigurationException(\"SPARSE mode doesn't support analyzers.\");\n        }\n\n        return Collections.emptyMap();\n    }\n\n    @Override\n    public void register(IndexRegistry registry)\n    {\n        registry.registerIndex(this, new Group.Key(this), () -> new SASIIndexGroup(this));\n    }\n\n    public IndexMetadata getIndexMetadata()\n    {\n        return config;\n    }\n\n    public Callable<?> getInitializationTask()\n    {","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sasi/SASIIndex.java#L164-L200","documentation":"SPARSE mode assumes unanalyzed, directly comparable tokens. When the resolved mode is SPARSE but mode.isAnalyzed is true (an analyzer was configured via 'analyzed': 'true' / analyzer_class), validateOptions throws this ConfigurationException.","triggerScenarios":"SASI index options combining 'mode': 'SPARSE' with 'analyzed': 'true' or a custom 'analyzer_class' on the target column.","commonSituations":"Copy-pasting analyzer settings into SPARSE index definitions; tooling that appends analyzer options by default; misunderstanding that analyzers apply to all modes.","solutions":["Remove the analyzer options ('analyzed' / 'analyzer_class') from the SPARSE index options.","Or change the mode to PREFIX/CONTAINS if tokenized/analyzed text search is actually wanted.","Validate the option combination locally before issuing CREATE CUSTOM INDEX."],"exampleFix":"// before\nWITH OPTIONS = {'target': 'created_at', 'mode': 'SPARSE', 'analyzed': 'true'};\n// after\nWITH OPTIONS = {'target': 'created_at', 'mode': 'SPARSE'};","handlingStrategy":"validation","validationCode":"// analyzer options are invalid with SPARSE\nif (\"SPARSE\".equals(options.get(\"mode\")) && (options.get(\"analyzed\") != null || options.get(\"analyzer_class\") != null))\n    throw new IllegalArgumentException(\"SPARSE mode does not support analyzers\");","typeGuard":null,"tryCatchPattern":"try {\n    session.execute(createIndexStmt);\n} catch (InvalidQueryException e) {\n    if (e.getMessage().contains(\"SPARSE mode doesn't support analyzers\")) { /* strip analyzer options or switch mode */ }\n}","preventionTips":["Keep analyzer options only in PREFIX/CONTAINS index templates.","Validate the full option matrix (mode x analyzed) in CI before deploying index migrations."],"tags":["sasi","invalid-config-value","analyzer","sparse-mode","cassandra"],"backgroundTag":"conflicting-config-options","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}