flowable/flowable-engine · error · FlowableIllegalArgumentException

This method is not supported in an OR statement

Error message

This method is not supported in an OR statement

What it means

processInstanceBusinessKey(String, String) cannot be combined with or() query composition; Flowable throws FlowableIllegalArgumentException when it is called inside an or() block. Only the single-argument processInstanceBusinessKey variant supports OR statements. This is an API restriction on which criteria methods are valid within a disjunction.

Solutions

1. Use the single-argument processInstanceBusinessKey(businessKey) inside the or() block and express the process definition constraint with processDefinitionKey(...) on the same or-operand scope if supported.
2. Move the combined businessKey+processDefinitionKey condition out of the or() block and AND it with the OR group instead.
3. Restructure the query into multiple queries and merge results in application code if the semantics require it.

Example fix

// before
query.or().processInstanceBusinessKey(bk, pdk).processInstanceNameLike(name).endOr();
// after
query.processDefinitionKey(pdk)
    .or().processInstanceBusinessKey(bk).processInstanceNameLike(name).endOr();

boolean inOr = query instanceof ProcessInstanceQueryImpl
        && ((ProcessInstanceQueryImpl) query).inOrStatement;
if (inOr) {
    throw new IllegalArgumentException("processInstanceBusinessKey(bk, pdk) is not allowed inside or(); use the single-arg overload");
}

try {
    query.or().processInstanceBusinessKey(bk, pdk).endOr();
} catch (FlowableIllegalArgumentException e) {
    if (!e.getMessage().contains("not supported in an OR statement")) throw e;
    // rebuild using the single-argument overload inside the OR block
}

When it happens

Trigger: runtimeService.createProcessInstanceQuery().or().processInstanceBusinessKey(bk, pdk)... — calling the two-arg overload after or() and before endOr().

Common situations: Refactoring an existing query into an or() block without noticing the two-arg overload is excluded; generating queries dynamically where the criteria set lands inside an OR statement; misunderstanding that both overloads behave identically.

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

• endOr() can only be called after calling or()
• the query is already in an or statement
• Business key is null
• Business status is null
• can't clear configuration beans

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java:195

    public ProcessInstanceQuery processInstanceBusinessKey(String businessKey) {
        if (businessKey == null) {
            throw new FlowableIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessKey = businessKey;
        } else {
            this.businessKey = businessKey;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceBusinessKey(String businessKey, String processDefinitionKey) {
        if (businessKey == null) {
            throw new FlowableIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            throw new FlowableIllegalArgumentException("This method is not supported in an OR statement");
        }

        this.businessKey = businessKey;
        this.processDefinitionKey = processDefinitionKey;
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceBusinessKeyLike(String businessKeyLike) {
        if (inOrStatement) {
            this.currentOrQueryObject.businessKeyLike = businessKeyLike;
        } else {
            this.businessKeyLike = businessKeyLike;
        }
        return this;
    }
    
    @Override

View on GitHub (pinned to d6d39ce1c6)