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 "" instead

What it means

When a Panache query string starts with '#', it is a named-query reference. Hibernate applies ordering inside the named query's HQL, so Panache refuses a separate Sort parameter rather than silently ignoring or conflicting with it.

Source

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

    }

    public int paramCount(Map<String, Object> params) {
        return params != null ? params.size() : 0;
    }

    //
    // Queries

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

    public PanacheQueryType find(Class<?> entityClass, String panacheQuery, Sort sort, Object... params) {
        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, null, params);
        }

        String translatedHqlQuery = PanacheJpaUtil.createFindQuery(entityClass, panacheQuery, paramCount(params));
        return createPanacheQuery(session, entityClass, translatedHqlQuery, 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) {
        SessionType session = getSession(entityClass);
        if (PanacheJpaUtil.isNamedQuery(panacheQuery)) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove the Sort argument from the call
2. Add an 'order by' clause inside the named query HQL itself
3. Use a plain HQL query string instead of the named query if you need dynamic sorting

Example fix

// before
repo.find("#Person.getAll", Sort.descending("name")).list();
// after: add 'order by name desc' to @NamedQuery and call
repo.find("#Person.getAll").list();

if (panacheQuery.startsWith("#") && sort != null) {
    throw new IllegalArgumentException("Remove Sort when using named query " + panacheQuery);
}

try {
    return find(entityClass, query, sort, params);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Sort cannot be used with named query")) {
        return find(entityClass, query, null, params);
    }
    throw e;
}

When it happens

Trigger: Calling find(entityClass, "#Person.findByName", Sort.descending("name"), params) — any find/list/stream call with a '#'-prefixed named query and a non-null Sort.

Common situations: Migrating from a dynamic query to a named query and keeping the old Sort argument; helper methods that always pass a Sort default; mixing Spring-Data-like API expectations with Panache named queries.

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
• Unable to load repository/entity class mapping ->
• Your repository class was not properly detected and assigne

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