flowable/flowable-engine · error · FlowableIllegalArgumentException

includeEnded is not allowed within an or query

Error message

includeEnded is not allowed within an or query

What it means

PlanItemInstanceQueryImpl.includeEnded() throws FlowableIllegalArgumentException when called inside an or-statement (between .or() and .endOr()). Including ended plan item instances is a query-level result-shaping flag, not a filterable column, so Flowable forbids combining it with or-criteria. The query must call includeEnded() only on the top-level query object.

Solutions

1. Move includeEnded() outside the or() ... endOr() block, onto the top-level query
2. Chain it before or after the or clause: query.includeEnded().or()...endOr()
3. Remove includeEnded() if ended instances should not be included
4. Rebuild the chain so only column-comparison criteria live inside the or block

Example fix

// before
query.or().planItemInstanceEndedAfter(date).includeEnded().endOr();
// after
query.includeEnded().or().planItemInstanceEndedAfter(date).endOr();

// includeEnded is a top-level flag: set it outside or() ... endOr()
query.includeEnded().or()/* criteria */.endOr();

try {
    query.includeEnded();
} catch (FlowableIllegalArgumentException e) {
    throw new IllegalStateException("includeEnded must be called outside an or() block", e);
}

When it happens

Trigger: Calling query.or().planItemInstanceXxx(...).includeEnded().endOr() or any placement of includeEnded() while inOrStatement is true.

Common situations: Developers chaining all criteria uniformly inside an or() block without realizing some flags are or-incompatible; refactoring a flat query into an or query by moving every method call inside or().

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• activatedBefore is null
• assignee is null
• availableAfter is null
• availableBefore is null
• before time is null

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java:686

        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery ended() {
        if (inOrStatement) {
            this.currentOrQueryObject.ended = true;
            includeEnded = true;
        } else {
            this.ended = true;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery includeEnded() {
        if (inOrStatement) {
            throw new FlowableIllegalArgumentException("includeEnded is not allowed within an or query");
        } else {
            this.includeEnded = true;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery started() {
        if (inOrStatement) {
            this.currentOrQueryObject.started = true;
        } else {
            this.started = true;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery notStarted() {

View on GitHub (pinned to d6d39ce1c6)