apache/cassandra · error · InvalidRequestException

Use of ANN OF in an ORDER BY clause requires a LIMIT that is

Error message

Use of ANN OF in an ORDER BY clause requires a LIMIT that is not greater than %s. LIMIT was %s

What it means

ANN (vector) queries limit top-K to MAX_TOP_K to protect the vector graph data structure from overflow and OOM during top-k filtering. StorageAttachedIndex.validate checks the command's LIMIT; if limits().count() exceeds MAX_TOP_K it throws this InvalidRequestException with the allowed maximum and the actual LIMIT.

Source

Thrown at src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java:539

        return (leftBuf, rightBuf) -> {
            float[] left = indexTermType.decomposeVector(leftBuf.duplicate());
            double scoreLeft = function.compare(left, target);

            float[] right = indexTermType.decomposeVector(rightBuf.duplicate());
            double scoreRight = function.compare(right, target);
            return Double.compare(scoreRight, scoreLeft); // descending order
        };
    }

    @Override
    public void validate(ReadCommand command) throws InvalidRequestException
    {
        if (!indexTermType.isVector())
            return;

        // to avoid overflow of the vector graph internal data structure and avoid OOM when filtering top-k
        if (command.limits().count() > MAX_TOP_K)
            throw new InvalidRequestException(String.format(ANN_LIMIT_ERROR, MAX_TOP_K, command.limits().count()));
    }

    @Override
    public long getEstimatedResultRows()
    {
        throw new UnsupportedOperationException("Use StorageAttachedIndexQueryPlan#getEstimatedResultRows() instead.");
    }

    @Override
    public boolean isQueryable(Status status)
    {
        // consider unknown status as queryable, because gossip may not be up-to-date for newly joining nodes.
        return status == Status.BUILD_SUCCEEDED || status == Status.UNKNOWN;
    }

    @Override
    public void validate(PartitionUpdate update, ClientState state) throws InvalidRequestException
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Reduce the LIMIT of the ANN ORDER BY query to <= MAX_TOP_K.
2. Issue multiple ANN queries with per-partition filters to distribute the top-k across queries.
3. Retrieve more results by narrowing the search space (e.g., additional WHERE filters) rather than a larger LIMIT.

Example fix

// before
SELECT ... FROM ks.tbl ORDER BY embedding ANN OF [0.1,...] LIMIT 5000;
// after
SELECT ... FROM ks.tbl ORDER BY embedding ANN OF [0.1,...] LIMIT 1000;

const MAX_TOP_K = 1000; if (query.orderBy?.type === 'ANN' && query.limit > MAX_TOP_K) throw new Error(`ANN LIMIT must be <= ${MAX_TOP_K}`);

catch (InvalidRequestException e) { if (e.getMessage().startsWith('Use of ANN OF in an ORDER BY clause requires a LIMIT')) { // clamp limit to the reported maximum and retry } }

When it happens

Trigger: Executing a SELECT with ORDER BY <vector_col> ANN OF [...] and LIMIT n where n > MAX_TOP_K (e.g., LIMIT 2000 when the cap is 1000).

Common situations: Bulk similarity search scripts requesting large result pages; application pagination implemented by raising LIMIT; default page sizes tuned for non-ANN queries.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• SAI ANN indexes are only allowed on vector columns with floa
• Cosine similarity is not supported for single-dimension vect
• SAI ANN indexes are not allowed on multiple data directories
• Unsupported expression during ANN index query:
• Cannot specify more than one ANN ordering

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