Top-K queries do not support paging and the page size is…

Error message

Top-K queries do not support paging and the page size is set to %d, which is less than LIMIT %d. The page size has been set to %d to match the LIMIT.

What it means

Top-K (ANN) queries do not support paging. If the configured page size is non-zero and smaller than the query LIMIT, the coordinator bumps the page size to the LIMIT so the whole top-K result is fetched in one page, and warns the client about the change.

Solutions

Set page size >= LIMIT for ANN queries, or remove explicit page-size settings
Set fetch size to the ANN LIMIT exactly (e.g. setPageSize(limit))
Use a dedicated execution profile for vector queries with an appropriate fetch size

Example fix

// before
statement.setPageSize(100); // with LIMIT 500 ANN query
// after
statement.setPageSize(500); // match the ANN LIMIT, paging unsupported

Defensive patterns

Strategy: validation

Validate before calling

if (isAnnQuery && pageSize > 0 && pageSize < limit) {
    pageSize = limit; // ANN queries do not support paging below LIMIT
}

Prevention

Match fetch size to ANN LIMIT
Use a separate execution profile for ANN queries
Keep a warning handler registered to observe page-size rewrites

When it happens

Trigger: Executing an ANN SELECT with LIMIT N while the driver page fetch size is set to a value between 1 and N-1; SelectStatement.execute rewrites the page size and warns via ClientWarn.

Common situations: Driver default fetch size (5000) exceeding ANN LIMIT is fine, but a reduced fetch size (e.g. setPageSize(100) for memory reasons) collides with a larger LIMIT; global driver config tuned for regular queries applied to vector queries.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/statements/SelectStatement.java:418

                ConsistencyLevel supplied = options.getConsistency();
                ConsistencyLevel downgrade = supplied.isDatacenterLocal() ? ConsistencyLevel.LOCAL_ONE : ConsistencyLevel.ONE;

                options = QueryOptions.withConsistencyLevel(options, downgrade);

                ClientWarn.instance.warn(String.format(TOPK_CONSISTENCY_LEVEL_WARNING, supplied, downgrade));
            }

            checkFalse(limit.isUnlimited(), TOPK_LIMIT_ERROR);

            checkFalse(limit.perPartitionCount() != DataLimits.NO_LIMIT, TOPK_PARTITION_LIMIT_ERROR);

            if (pageSize > 0 && pageSize < limit.count())
            {
                int oldPageSize = pageSize;
                pageSize = limit.count();
                limit = getDataLimits(userLimit, userPerPartitionLimit, pageSize, aggregationSpec);
                options = QueryOptions.withPageSize(options, pageSize);
                ClientWarn.instance.warn(String.format(TOPK_PAGE_SIZE_WARNING, oldPageSize, limit.count(), pageSize));
            }
        }

        ReadQuery query = getQuery(options, state.getClientState(), selectors.getColumnFilter(), nowInSec, limit, PotentialTxnConflicts.DISALLOW);

        if (options.isReadThresholdsEnabled())
            query.trackWarnings();
        ResultMessage.Rows rows;

        if (aggregationSpec == null && (pageSize <= 0 || (query.limits().count() <= pageSize) || query.isTopK()))
        {
            rows = execute(query, options, state.getClientState(), selectors, nowInSec, userLimit, null, requestTime, unmask);
        }
        else
        {
            QueryPager pager = getPager(query, options);

            rows = execute(state,

View on GitHub (pinned to 88fd0f6a0e)