quarkusio/quarkus · error · IllegalArgumentException

Sort cannot be used with named query, add an "order by"…

Error message

Sort cannot be used with named query, add an "order by" clause to the named query "${namedQuery}" instead

What it means

Panache's find() detects named queries by the leading '#'. A Sort parameter cannot be applied to a named query because sorting must be part of the query itself, so an IllegalArgumentException is thrown, directing you to add an ORDER BY clause to the named query.

Solutions

Remove the Sort argument and add 'ORDER BY <column>' inside the @NamedQuery HQL
Keep the sort in the query string and pass Sort.nullValue() / null
Convert the named query back to an inline HQL/panache query if dynamic sorting is needed

Example fix

// before
NamedQueries: @NamedQuery(name="Person.findByName", query="from Person p where p.name = :name")
find("#Person.findByName", Sort.descending("name"), name)
// after
@NamedQuery(name="Person.findByName", query="from Person p where p.name = :name order by p.name desc")
find("#Person.findByName", name)

Defensive patterns

Strategy: try-catch

Validate before calling

if (panacheQuery.startsWith("#") && sort != null)
    throw new IllegalArgumentException("Passing Sort with named query " + panacheQuery + " is not allowed");

Try / catch

try {
    return operations.find(entityClass, query, sort, params);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Sort cannot be used with named query")) {
        throw new IllegalArgumentException("Move ordering into the named query's ORDER BY clause", e);
    }
    throw e;
}

Prevention

Embed ORDER BY in named queries
Never pass Sort when the query string starts with '#'
Centralize query constants so named-query usage is greppable

When it happens

Trigger: Calling PanacheCriteria/AbstractJpaOperations.find(entityClass, "#NamedQuery", Sort.descending("name"), params...) — i.e. any find/list overloads that take both a '#'-prefixed named query and a non-null Sort.

Common situations: Reusing a find-with-sort helper against a named query constant; switching a HQL string to a named query while keeping the Sort argument.

Related errors

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

Appendix: source

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

    public Uni<?> findById(Class<?> entityClass, Object id) {
        return getSession(entityClass).chain(session -> find(session, entityClass, id));
    }

    public Uni<?> findById(Class<?> entityClass, Object id, LockModeType lockModeType) {
        return getSession(entityClass)
                .chain(session -> find(session, entityClass, id, LockModeConverter.convertToLockMode(lockModeType)));
    }

    public PanacheQueryType find(Class<?> entityClass, String panacheQuery, Object... params) {
        return find(entityClass, panacheQuery, null, params);
    }

    public PanacheQueryType find(Class<?> entityClass, String panacheQuery, Sort sort, Object... params) {
        Uni<SessionType> session = getSession(entityClass);
        if (PanacheJpaUtil.isNamedQuery(panacheQuery)) {
            String namedQuery = panacheQuery.substring(1);
            if (sort != null) {
                throw new IllegalArgumentException(
                        "Sort cannot be used with named query, add an \"order by\" clause to the named query \"" + namedQuery
                                + "\" instead");
            }
            NamedQueryUtil.checkNamedQuery(entityClass, namedQuery);
            return createPanacheQuery(session, entityClass, panacheQuery, panacheQuery, sort, params);
        }
        String hqlQuery = PanacheJpaUtil.createFindQuery(entityClass, panacheQuery, paramCount(params));
        return createPanacheQuery(session, entityClass, hqlQuery, panacheQuery, sort, params);
    }

    public PanacheQueryType find(Class<?> entityClass, String panacheQuery, Map<String, Object> params) {
        return find(entityClass, panacheQuery, null, params);
    }

    public PanacheQueryType find(Class<?> entityClass, String panacheQuery, Sort sort, Map<String, Object> params) {
        Uni<SessionType> session = getSession(entityClass);
        if (PanacheJpaUtil.isNamedQuery(panacheQuery)) {
            String namedQuery = panacheQuery.substring(1);

View on GitHub (pinned to e1c734241f)