apache/cassandra · error · IllegalArgumentException

Unsupported expression:

Error message

Unsupported expression: 

What it means

LiteralIndexSegmentSearcher.search() only supports equality matching on literal SAI segments; expressions with other index operators (LIKE prefix/suffix/s contains, CONTAINS KEY, ranges) are rejected by the segment-level trie searcher, which implements only exactMatch. The IllegalArgumentException is annotated with the index identifier for context.

Solutions

1. Restructure the query to use equality on the indexed literal column, or add a text analyzer index supporting the operator (e.g. SAI text indexes for LIKE).
2. Check the Cassandra version — upgrade if the needed operator (e.g. LIKE) is unsupported on your SAI format version.
3. If the operator should be supported, it's a query-planning bug: it routed a non-equality expression to the exact-match searcher; report with the query and version.

Example fix

// before
SELECT * FROM t WHERE c LIKE '%foo'; // unsupported on this searcher
// after
SELECT * FROM t WHERE c = 'foo';

if (expression.getIndexOperator() == null || !expression.getIndexOperator().isEquality())
  throw new IllegalArgumentException("Only equality supported on this segment searcher");

boolean isEquality(Expression e) { return e.getIndexOperator() != null && e.getIndexOperator().isEquality(); }

try { return searcher.search(expr, range, ctx); } catch (IllegalArgumentException e) { log.warn("Unsupported operator for SAI segment", e); return KeyRangeIterator.empty(); }

When it happens

Trigger: Executing a query whose expression reaches a v1 LiteralIndexSegmentSearcher with getIndexOperator() != equality — e.g. a LIKE '%foo' suffix query routed to a segment searcher that only handles exact terms.

Common situations: Running text queries (LIKE with wildcards, CONTAINS) against an index/segment implementation that doesn't support that operation, or version-skew where an operator was added before segment searchers supported it.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• QueryCancelledException(readCommand)
• Unsupported expression during index query:
• A storage-attached index cannot be created over multiple…
• An error occurred while scrubbing the partition with key
• Analysis options are not supported on primary key columns…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/segment/LiteralIndexSegmentSearcher.java:86

        reader = new LiteralIndexSegmentTermsReader(index.identifier(), indexFiles.termsData(), indexFiles.postingLists(), root, footerPointer);
    }

    @Override
    public long indexFileCacheSize()
    {
        // trie has no pre-allocated memory.
        return 0;
    }

    @Override
    public KeyRangeIterator search(Expression expression, AbstractBounds<PartitionPosition> keyRange, QueryContext queryContext) throws IOException
    {
        if (logger.isTraceEnabled())
            logger.trace(index.identifier().logMessage("Searching on expression '{}'..."), expression);

        if (!expression.getIndexOperator().isEquality())
            throw new IllegalArgumentException(index.identifier().logMessage("Unsupported expression: " + expression));

        ByteComparable term = v -> index.termType().asComparableBytes(expression.lower().value.encoded, v);
        QueryEventListener.TrieIndexEventListener listener = MulticastQueryEventListeners.of(queryContext, perColumnEventListener);
        return toPrimaryKeyIterator(reader.exactMatch(term, listener, queryContext), queryContext);
    }

    @Override
    public String toString()
    {
        return MoreObjects.toStringHelper(this).add("index", index).toString();
    }

    @Override
    public void close()
    {
        reader.close();
    }
}

View on GitHub (pinned to 88fd0f6a0e)