flowable/flowable-engine · error · FlowableIllegalArgumentException

Business status is null

Error message

Business status is null

What it means

HistoricCaseInstanceQueryImpl.caseInstanceBusinessStatus() rejects a null business status string up front. A null value would produce an invalid equality predicate in the generated SQL, so Flowable throws FlowableIllegalArgumentException immediately instead of deferring failure to query execution. To clear a business status filter, build a fresh query rather than passing null.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java:461

    }

    @Override
    public HistoricCaseInstanceQuery caseInstanceParentScopeIds(Set<String> parentScopeIds) {
        if (parentScopeIds == null || parentScopeIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("parentScopeIds is null or empty");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.parentScopeIds = parentScopeIds;
        } else {
            this.parentScopeIds = parentScopeIds;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceBusinessStatus(String businessStatus) {
        if (businessStatus == null) {
            throw new FlowableIllegalArgumentException("Business status is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessStatus = businessStatus;
        } else {
            this.businessStatus = businessStatus;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceBusinessStatusLike(String businessStatusLike) {
        if (businessStatusLike == null) {
            throw new FlowableIllegalArgumentException("Business status is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessStatusLike = businessStatusLike;
        } else {
            this.businessStatusLike = businessStatusLike;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null business status string, e.g. caseInstanceBusinessStatus("approved").
2. Skip the call when the value is null so no business-status filter is applied.
3. Default null to a sentinel or use a builder pattern that only applies set filters.
4. Catch FlowableIllegalArgumentException and surface a client-side validation message.

Example fix

// before
query.caseInstanceBusinessStatus(request.getBusinessStatus());
// after
if (request.getBusinessStatus() != null) {
    query.caseInstanceBusinessStatus(request.getBusinessStatus());
}

if (businessStatus != null) {
    query.caseInstanceBusinessStatus(businessStatus);
}

boolean hasText(String s) {
    return s != null && !s.isBlank();
}

try {
    query.caseInstanceBusinessStatus(status);
} catch (FlowableIllegalArgumentException e) {
    throw new InvalidRequestException("businessStatus is required: " + e.getMessage());
}

When it happens

Trigger: Calling historicCaseInstanceQuery.caseInstanceBusinessStatus(null), including inside an or() compound where the value is stored on the currentOrQueryObject only after this null check passes.

Common situations: Mapping a REST/GraphQL request field (optional businessStatus) directly into the query; deserialization leaves the field null when the client omitted it, and the code forwards it unconditionally.

Related errors

• query is null
• parentScopeIds is null or empty
• Case definition keys is null
• tenant id is null
• variableNames is null or empty

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