flowable/flowable-engine · error · ActivitiIllegalArgumentException

You should call any of the orderBy methods first before…

Error message

You should call any of the orderBy methods first before specifying a direction

What it means

AbstractQuery.direction(Direction) applies asc/desc to the property most recently selected via an orderByXX() method. If direction() is called (directly or through asc()/desc()) before any orderBy call, orderProperty is null and ActivitiIllegalArgumentException is thrown. The query API requires sort property first, then direction.

Solutions

1. Call an orderByXX() method before asc()/desc(), e.g. query.orderByTaskCreateTime().desc().
2. If ordering is optional, guard: only call asc()/desc() when a sort property was chosen.
3. Never call direction() directly unless you know orderProperty was set by a preceding orderBy call.

Example fix

// before
TaskQuery q = taskService.createTaskQuery().taskAssignee(user).desc(); // throws
// after
TaskQuery q = taskService.createTaskQuery().taskAssignee(user).orderByTaskCreateTime().desc();

if (sortProperty != null) { query = query.orderBy(sortProperty); if (ascending) query = query.asc(); else query = query.desc(); }

try { return query.asc().list(); } catch (ActivitiIllegalArgumentException e) { logger.warn("asc()/desc() without orderBy"); return query.list(); }

When it happens

Trigger: query.desc() / query.asc() / query.direction(Direction.DESCENDING) without a preceding orderByTaskCreateTime(), orderByProcessInstanceId(), etc.

Common situations: Dynamic query building where the orderBy call is behind a conditional branch that did not execute; copying API usage from other query frameworks that put direction first; refactors removing the orderBy line while keeping asc()/desc().

Related errors

• Invalid query: call asc() or desc() after using orderByXX()
• Case definition category is null
• Case definition id is null
• Case definition key is null
• name is null

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/63bc6cdfccea22ee. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/AbstractQuery.java:111

        orderBy(property);
        this.nullHandlingOnOrder = nullHandlingOnOrder;
        return (T) this;
    }

    @Override
    public T asc() {
        return direction(Direction.ASCENDING);
    }

    @Override
    public T desc() {
        return direction(Direction.DESCENDING);
    }

    @SuppressWarnings("unchecked")
    public T direction(Direction direction) {
        if (orderProperty == null) {
            throw new ActivitiIllegalArgumentException("You should call any of the orderBy methods first before specifying a direction");
        }
        addOrder(orderProperty.getName(), direction.getName(), nullHandlingOnOrder);
        orderProperty = null;
        nullHandlingOnOrder = null;
        return (T) this;
    }

    protected void checkQueryOk() {
        if (orderProperty != null) {
            throw new ActivitiIllegalArgumentException("Invalid query: call asc() or desc() after using orderByXX()");
        }
    }

    @Override
    @SuppressWarnings("unchecked")
    public U singleResult() {
        this.resultType = ResultType.SINGLE_RESULT;
        if (commandExecutor != null) {

View on GitHub (pinned to d6d39ce1c6)