quarkusio/quarkus · error · IllegalArgumentException

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

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.

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)

Solutions

1. Remove the Sort argument and add 'ORDER BY <column>' inside the @NamedQuery HQL
2. Keep the sort in the query string and pass Sort.nullValue() / null
3. 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)

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

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;
}

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

• Sort cannot be used with named query, add an "order by" clau
• Must be a named query!
• Cannot use cursor-based pagination without sort criteria: us
• %s entities do not support being attached to several persist
• Entity '%s' was not found. Did you forget to annotate your P

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