What causes "The page size cannot be 0" in apache/cassandra?

Use a positive page size (e.g. 1000–5000) or Integer.MAX_VALUE for unpaged results

apache/cassandra · error · ProtocolException

The page size cannot be 0

Error message

The page size cannot be 0

What it means

ProtocolException from QueryMessage.execute when the client supplies a paging state request with page size exactly 0. Page size 0 is undefined in the native protocol (negative means unlimited); zero is rejected before statement execution so the driver receives a protocol error rather than a broken result page.

Source

Thrown at src/java/org/apache/cassandra/transport/messages/QueryMessage.java:109

    protected boolean isTraceable()
    {
        return true;
    }

    @Override
    protected boolean isTrackable()
    {
        return true;
    }

    @Override
    protected Message.Response execute(QueryState state, Dispatcher.RequestTime requestTime, boolean traceRequest)
    {
        CQLStatement statement = null;
        try
        {
            if (options.getPageSize() == 0)
                throw new ProtocolException("The page size cannot be 0");

            if (traceRequest)
                traceQuery(state);

            long queryStartTime = currentTimeMillis();

            QueryHandler queryHandler = ClientState.getCQLQueryHandler();
            statement = queryHandler.parse(query, state, options);
            Message.Response response = queryHandler.process(statement, state, options, getCustomPayload(), requestTime);
            QueryEvents.instance.notifyQuerySuccess(statement, query, options, state, queryStartTime, response);

            if (options.skipMetadata() && response instanceof ResultMessage.Rows)
                ((ResultMessage.Rows)response).result.metadata.setSkipMetadata();

            return response;
        }
        catch (Exception e)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Use a positive page size (e.g. 1000–5000) or Integer.MAX_VALUE for unpaged results
Let the driver auto-page via iterator/executeAsync paging instead of manual paging options
Validate/normalize page size at the config boundary, treating 0 or negative as "use default"
Omit page size option when defaults are acceptable

Example fix

// before
QueryMessage msg = new QueryMessage(cql, optsWithPageSize(0));
// after
QueryMessage msg = new QueryMessage(cql, optsWithPageSize(5000));

Defensive patterns

Strategy: validation

Validate before calling

if (opts.getPageSize() == 0)
    throw new IllegalArgumentException("page size must be positive; use Integer.MAX_VALUE for no paging");

Try / catch

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

Prevention

Never pass user-controlled page size straight into fetch size
Treat 0/negative page size as "use default" during config load
Rely on driver paging iterators instead of manual sizing
Log and normalize invalid page-size values at startup

When it happens

Trigger: Sending a QueryMessage (simple, non-prepared query) with query options whose getPageSize() == 0 — e.g. setting fetch size 0 to mean "no limit" instead of using a positive number or MAX_VALUE.

Common situations: Config values defaulting to 0 wired into the driver's fetch size; hand-rolled protocol clients computing pageSize from user input; language bindings that pass 0 through unchecked.

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

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