apache/cassandra · error · ProtocolException

The page size cannot be 0

Error message

The page size cannot be 0

What it means

The CQL binary protocol requires a positive page size when paging is requested. ExecuteMessage rejects a page size of exactly 0 with a ProtocolException before running the statement, since 0 would mean an infinite/invalid page.

Source

Thrown at src/java/org/apache/cassandra/transport/messages/ExecuteMessage.java:156

            prepared = handler.getPrepared(statementId);
            if (prepared == null)
                throw new PreparedQueryNotFoundException(statementId);

            if (!prepared.fullyQualified && prepared.statement.eligibleAsPreparedStatement() && !Objects.equals(state.getClientState().getRawKeyspace(), prepared.keyspace))
            {
                state.getClientState().warnAboutUseWithPreparedStatements(statementId, prepared.keyspace);

                String msg = String.format("Tried to execute a prepared unqualified statement on a keyspace it was not prepared on. " +
                                           " Executing the resulting prepared statement will return unexpected results: %s (on keyspace %s, previously prepared on %s)",
                                           statementId, state.getClientState().getRawKeyspace(), prepared.keyspace);
                nospam.error(msg);
            }

            CQLStatement statement = prepared.statement;
            options.prepare(statement.getBindVariables());

            if (options.getPageSize() == 0)
                throw new ProtocolException("The page size cannot be 0");

            if (traceRequest)
                traceQuery(state, prepared);

            if (options.isEligibleForArtificialLatency())
                ArtificialLatency.setEligibleForArtificialLatency(true);

            // Some custom QueryHandlers are interested by the bound names. We provide them this information
            // by wrapping the QueryOptions.
            QueryOptions queryOptions = QueryOptions.addColumnSpecifications(options, prepared.statement.getBindVariables());

            long requestStartTime = currentTimeMillis();

            Message.Response response = handler.processPrepared(statement, state, queryOptions, getCustomPayload(), requestTime);

            QueryEvents.instance.notifyExecuteSuccess(prepared.statement, prepared.rawCQLStatement, options, state, requestStartTime, response);

            if (response instanceof ResultMessage.Rows)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set the fetch size to a positive value (e.g. 5000) instead of 0
2. To fetch everything, use the maximum fetch size (Integer.MAX_VALUE) or use the driver's "no paging"/auto-paging iteration API
3. Validate user- or config-supplied page sizes and reject/normalize 0 before sending
4. Omit the paging options entirely if you don't intend to page

Example fix

// before
statement.setFetchSize(0); // illegal
// after
statement.setFetchSize(5000); // or Integer.MAX_VALUE for all rows

int pageSize = config.pageSize();
if (pageSize <= 0)
    pageSize = 5000; // normalize to default
statement.setFetchSize(pageSize);

int safePageSize(Integer n) {
    return (n == null || n <= 0) ? 5000 : n;
}

try {
    session.execute(statement);
} catch (ProtocolException e) {
    if (e.getMessage().contains("page size cannot be 0"))
        session.execute(statement.setFetchSize(5000));
    else throw e;
}

When it happens

Trigger: Sending ExecuteMessage whose query options carry pageSize == 0 — typically a client setting fetch size to 0 intending "unlimited" instead of omitting paging or using a positive value / Integer.MAX_VALUE.

Common situations: Application code that maps a UI/config "page size" input straight into the driver fetch size; misinterpreting protocol docs; rounding/config parsing producing 0.

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

• The page size cannot be 0
• There were %d markers(?) in CQL but %d bound variables
• Invalid null value of timestamp
• A TTL must be greater or equal to 0, but was <ttl>
• ttl is too large. requested (%d) maximum (%d)

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