apache/cassandra · error · ConfigurationException

SPARSE mode doesn't support analyzers.

Error message

SPARSE mode doesn't support analyzers.

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/index/sasi/SASIIndex.java:182

        if (target == null)
            throw new ConfigurationException("failed to retrieve target column for: " + targetColumn);

        if (target.left.isComplex())
            throw new ConfigurationException("complex columns are not yet supported by SASI");

        if (target.left.isPartitionKey())
            throw new ConfigurationException("partition key columns are not yet supported by SASI");

        IndexMode.validateAnalyzer(options, target.left);

        IndexMode mode = IndexMode.getMode(target.left, options);
        if (mode.mode == Mode.SPARSE)
        {
            if (mode.isLiteral)
                throw new ConfigurationException("SPARSE mode is only supported on non-literal columns.");

            if (mode.isAnalyzed)
                throw new ConfigurationException("SPARSE mode doesn't support analyzers.");
        }

        return Collections.emptyMap();
    }

    @Override
    public void register(IndexRegistry registry)
    {
        registry.registerIndex(this, new Group.Key(this), () -> new SASIIndexGroup(this));
    }

    public IndexMetadata getIndexMetadata()
    {
        return config;
    }

    public Callable<?> getInitializationTask()
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove the analyzer options ('analyzed' / 'analyzer_class') from the SPARSE index options.
2. Or change the mode to PREFIX/CONTAINS if tokenized/analyzed text search is actually wanted.
3. Validate the option combination locally before issuing CREATE CUSTOM INDEX.

Example fix

// before
WITH OPTIONS = {'target': 'created_at', 'mode': 'SPARSE', 'analyzed': 'true'};
// after
WITH OPTIONS = {'target': 'created_at', 'mode': 'SPARSE'};

// analyzer options are invalid with SPARSE
if ("SPARSE".equals(options.get("mode")) && (options.get("analyzed") != null || options.get("analyzer_class") != null))
    throw new IllegalArgumentException("SPARSE mode does not support analyzers");

try {
    session.execute(createIndexStmt);
} catch (InvalidQueryException e) {
    if (e.getMessage().contains("SPARSE mode doesn't support analyzers")) { /* strip analyzer options or switch mode */ }
}

When it happens

Trigger: SASI index options combining 'mode': 'SPARSE' with 'analyzed': 'true' or a custom 'analyzer_class' on the target column.

Common situations: Copy-pasting analyzer settings into SPARSE index definitions; tooling that appends analyzer options by default; misunderstanding that analyzers apply to all modes.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• %s does not support type %s
• SPARSE mode is only supported on non-literal columns.
• SASI indexes are disabled. Enable in cassandra.yaml to use.
• CQL type
• 'null' deserialized value for %s with %s

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