quarkusio/quarkus · error · UnsupportedOperationException

Cannot call a range related method, call range(int, int) to

Error message

Cannot call a range related method, call range(int, int) to initiate range first

What it means

Thrown by the Hibernate ORM Panache query's range guard when a range-related accessor is called on a query that never had range(int, int) applied. Panache queries can be in one pagination mode — page, keyed page, or range; calling a range method (mirroring the sibling checkPagination guard that rejects page methods without page(...)) without first initiating a range leaves the range state null, and the guard prevents reading an undefined range.

Source

Thrown at extensions/panache/hibernate-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/panache/common/runtime/CommonPanacheQueryImpl.java:298

    public Page page() {
        checkPagination();
        return page;
    }

    private void checkPagination() {
        if (page == null && keyedPage == null) {
            throw new UnsupportedOperationException("Cannot call a page related method, " +
                    "call page(Page) or page(int, int) to initiate pagination first");
        }
        if (range != null) {
            throw new UnsupportedOperationException("Cannot call a page related method in a ranged query, " +
                    "call page(Page) or page(int, int) to initiate pagination first");
        }
    }

    private void checkRange() {
        if (range == null) {
            throw new UnsupportedOperationException("Cannot call a range related method, " +
                    "call range(int, int) to initiate range first");
        }
        if (page != null) {
            throw new UnsupportedOperationException("Cannot call a range related method in a paged query, " +
                    "call range(int, int) to initiate range first");
        }
    }

    public Range range() {
        checkRange();
        return range;
    }

    public void range(int startIndex, int lastIndex) {
        this.range = Range.of(startIndex, lastIndex);
        this.page = null;
        this.keyedPage = null;
        this.lastKeyedResult = null;

View on GitHub (pinned to e1c734241f)

Solutions

Call range(int from, int to) before reading the range().
Use page(Page) if you actually meant pagination, then read page() instead of range().
Handle the absent-range case in your code before accessing the accessor.

Example fix

// before
PanacheQuery<Person> q = Person.find("status", "active");
Range r = q.range(); // throws

// after
PanacheQuery<Person> q = Person.find("status", "active").range(0, 49);
Range r = q.range();

Defensive patterns

Strategy: validation

Validate before calling

if (rangeWasNotSet) {
    query.range(0, defaultTo - 1);
}
Range r = query.range();

Try / catch

try {
    return query.range();
} catch (UnsupportedOperationException e) {
    return null; // no range configured
}

Prevention

Call range(from, to) before reading range().
Only use the range() accessor in code paths that configured a range.
Prefer pagination APIs unless a fixed window is genuinely required.

When it happens

Trigger: Calling query.range() (the accessor returning Range) on a PanacheQuery where range(int, int) was never invoked.

Common situations: Assuming a default range exists; reading back query window settings that were never configured.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/35468a00d6ccb669. Report an issue: GitHub.