apache/cassandra · error · IllegalArgumentException

Unsupported expression during ANN index query:

Error message

Unsupported expression during ANN index query: 

What it means

IllegalArgumentException thrown by VectorIndexSegmentSearcher.orderBy when the ORDER BY expression reaching the ANN searcher does not have IndexOperator.ANN. The vector searcher only handles ANN (approximate nearest neighbor) ordering; any other operator means the query was misrouted or used an unsupported operator on a vector index.

Source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/segment/VectorIndexSegmentSearcher.java:120

        return graph.ramBytesUsed();
    }

    @Override
    public KeyRangeIterator search(Expression expression, AbstractBounds<PartitionPosition> keyRange, QueryContext queryContext) throws IOException
    {
        throw new UnsupportedOperationException();
    }

    @Override
    public CloseableIterator<PrimaryKeyWithScore> orderBy(Expression orderer, AbstractBounds<PartitionPosition> keyRange, QueryContext context) throws IOException
    {
        int limit = context.limit();

        if (logger.isTraceEnabled())
            logger.trace(index.identifier().logMessage("Searching on expression '{}'..."), orderer);

        if (orderer.getIndexOperator() != Expression.IndexOperator.ANN)
            throw new IllegalArgumentException(index.identifier().logMessage("Unsupported expression during ANN index query: " + orderer));

        int topK = optimizeFor.topKFor(limit);

        float[] queryVector = index.termType().decomposeVector(orderer.lower().value.raw.duplicate());
        CloseableIterator<RowIdWithScore> result = searchInternal(keyRange, queryVector, limit, topK);
        return toScoreSortedIterator(result);
    }

    private CloseableIterator<RowIdWithScore> searchInternal(AbstractBounds<PartitionPosition> keyRange, float[] queryVector, int limit, int topK) throws IOException
    {
        try (PrimaryKeyMap primaryKeyMap = primaryKeyMapFactory.newPerSSTablePrimaryKeyMap())
        {
            // not restricted
            if (RangeUtil.coversFullRing(keyRange))
                return searchInternalUnrestricted(queryVector, limit, topK);


            // it will return the next row id if given key is not found.

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use the required ANN syntax: ORDER BY vector_col ANN OF [ ... ] LIMIT n
2. Rewrite the query without the unsupported operator, or filter on a non-vector index instead
3. Ensure all nodes run the same Cassandra version so planner and searcher agree on routing
4. If a valid ANN query hits this, file a bug with the exact CQL statement

Example fix

// before
SELECT ... FROM t ORDER BY embedding;              // not ANN
// after
SELECT ... FROM t ORDER BY embedding ANN OF [0.1, 0.2, ...] LIMIT 10;

if (orderer.getIndexOperator() != Expression.IndexOperator.ANN)
    throw new IllegalArgumentException("ORDER BY on a vector index must use ANN OF");

boolean isAnnOrdering(RowIdWithScoreOrderer o) {
    return o != null && o.getIndexOperator() == Expression.IndexOperator.ANN;
}

try {
    return vectorSearcher.orderBy(orderer, ...);
} catch (IllegalArgumentException e) {
    logger.warn("Non-ANN ordering rejected: {}", e.getMessage());
    throw new InvalidRequestException("Use ORDER BY col ANN OF [vector]");
}

When it happens

Trigger: Executing an ORDER BY ... ANN query against a vector column where the orderer's index operator is not ANN, e.g. a plain ORDER BY on the vector column, or routing/query-planning bugs that send non-ANN expressions to the vector searcher.

Common situations: Malformed CQL ORDER BY clause on a vector index, version skew between planner and searcher code, or attempting similarity search with an operator the vector index does not support.

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

• Cannot specify more than one ANN ordering
• ANN ordering does not support any other ordering
• Descending ANN ordering is not supported
• Use of ANN OF in an ORDER BY clause requires a LIMIT that is
• non-finite value at vector[

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