quarkusio/quarkus · error · UnsupportedOperationException

Cannot call a range related method in a paged query, call ra

Error message

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

What it means

Thrown by CommonAbstractPanacheQueryImpl.checkRange when a range-related method is called on a query that is in paged mode (page != null). Panache queries support either pagination (page(Page)) or a fixed range (range(int,int)), never both at once; switching from page to range resets the page, but the reverse mix triggers this error. It is an UnsupportedOperationException for incompatible query configuration.

Source

Thrown at extensions/panache/hibernate-reactive-panache-common/runtime/src/main/java/io/quarkus/hibernate/reactive/panache/common/runtime/CommonAbstractPanacheQueryImpl.java:226

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

    public void range(int startIndex, int lastIndex) {
        this.range = Range.of(startIndex, lastIndex);
        // reset the page to its default to be able to switch from page to range
        this.page = null;
    }

    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 void withLock(LockModeType lockModeType) {
        this.lockModeType = lockModeType;
    }

    public void withHint(String hintName, Object value) {
        if (hints == null) {
            hints = new HashMap<>();
        }
        hints.put(hintName, value);
        throw new UnsupportedOperationException("Hints not supported yet");
    }

    // Results

View on GitHub (pinned to e1c734241f)

Solutions

Remove the page(...) call so the query is not in paged mode before applying range(int,int).
Choose one mode: use page(int,int) + page accessors for pagination, or range(int,int) alone for a one-shot window.
Use a fresh PanacheQuery instance for the ranged variant instead of reusing a paged one.

Example fix

// before
PanacheQuery<Person> q = Person.find("age > ?1", 18).page(0, 20);
q.range(0, 50); // UnsupportedOperationException

// after
PanacheQuery<Person> q = Person.find("age > ?1", 18).range(0, 50);

Defensive patterns

Strategy: validation

Validate before calling

if (isPaged(query)) { throw new IllegalStateException("Cannot apply range to a paged query"); } // keep a boolean when you call .page(...)

Try / catch

try { query.range(start, end); } catch (UnsupportedOperationException e) { query = baseQuery().range(start, end); }

Prevention

One mode per query: choose page() or range() at construction time
Create a fresh PanacheQuery from the base find()/query() when switching modes
Encapsulate paging vs ranging in repository helpers so callers cannot mix them

When it happens

Trigger: Calling range(int,int) (or range accessor) on a PanacheQuery on which page(Page) or page(int,int) was previously called without any way to have cleared paging state; interleaving paging and ranging helpers on the same query object.

Common situations: Refactored code that switched a query from page() to range() but left page-related calls in place, or utility code that applies range() to a query already configured by a caller with page().

Related errors

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