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.

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)

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:
• Reversed queries are not supported.
• The 'key' column can only be used in an equality query for t
• Range queries are not supported. Please provide both a keysp

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