apache/cassandra · error · ConfigurationException

SPARSE mode is only supported on non-literal columns.

Error message

SPARSE mode is only supported on non-literal columns.

What it means

The SPARSE SASI mode is an optimization for low-cardinality, non-literal (numeric/timestamp) columns. When IndexMode.getMode returns Mode.SPARSE but the resolved mode is for a literal (text-like) column, validateOptions throws this ConfigurationException because SPARSE token layout is meaningless for strings.

Source

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

            throw new ConfigurationException("unknown target column");

        Pair<ColumnMetadata, IndexTarget.Type> target = TargetParser.parse(metadata, targetColumn);
        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;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Change mode to PREFIX, CONTAINS, or SUFFIX (omit to use the default) for the literal column.
If SPARSE is intended, confirm the target column is a non-literal type (int, bigint, timestamp, etc.).
Remove the 'mode' option entirely to let SASI pick the appropriate default.

Example fix

// before (column 'email' is text)
WITH OPTIONS = {'target': 'email', 'mode': 'SPARSE'};
// after
WITH OPTIONS = {'target': 'email', 'mode': 'CONTAINS', 'analyzed': 'true', 'analyzer_class': 'org.apache.cassandra.index.sasi.analyzer.StandardAnalyzer'};

Defensive patterns

Strategy: validation

Validate before calling

// only allow SPARSE on non-literal types
if ("SPARSE".equals(options.get("mode")) && isLiteralType(columnType))
    throw new IllegalArgumentException("SPARSE mode requires a non-literal column");

Try / catch

try {
    session.execute(createIndexStmt);
} catch (InvalidQueryException e) {
    if (e.getMessage().contains("SPARSE mode is only supported")) { /* drop or change the mode option */ }
}

Prevention

Map column types to allowed modes in config tooling (SPARSE only for numeric/date columns).
Prefer the default mode unless SPARSE is a measured win.

When it happens

Trigger: Declaring 'mode': 'SPARSE' in SASI index options on a text/ascii/varchar (literal-typed) target column.

Common situations: Copying SPARSE configuration from a numeric-column example onto a text column; bulk-configuring indexes with a single mode string regardless of column type.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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