flowable/flowable-engine · error · FlowableIllegalArgumentException

Business status is null

Error message

Business status is null

What it means

Flowable's CaseInstanceQueryImpl throws FlowableIllegalArgumentException when caseInstanceBusinessStatus(String) is called with null. The business status is a user-managed state string on case instances (set via setBusinessStatus); filtering by a null status is rejected up front because it would not be a valid query condition. Pass a concrete status string.

Solutions

1. Null-check the status before calling; only apply the criterion when a status is present
2. If 'any status' is intended, omit the criterion rather than passing null
3. Validate that the status value is one your application actually sets on case instances
4. Populate the status source (form/config) or make it a required API parameter

Example fix

// before
query.caseInstanceBusinessStatus(statusFilter); // may be null
// after
if (statusFilter != null) {
    query.caseInstanceBusinessStatus(statusFilter);
}

if (businessStatus == null) {
    return query; // no status filter
}
query.caseInstanceBusinessStatus(businessStatus);

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

try {
    query.caseInstanceBusinessStatus(businessStatus);
} catch (FlowableIllegalArgumentException e) {
    throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "businessStatus filter must not be null");
}

When it happens

Trigger: Calling caseInstanceBusinessKeyStatus alias caseInstanceBusinessStatus(null); forwarding an optional status filter from a request/DTO that was not provided; using a variable expected to hold the status that was never initialized.

Common situations: Dashboards filtering by business status where the status dropdown default is null; refactoring between businessKey and businessStatus methods and passing the wrong (null) field; older data model code where businessStatus was not yet tracked.

Related errors

• Business key is null
• callbackIds is null or empty
• callbackType is null
• Case definition keys is null
• id is null

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

Appendix: source

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

    }
    
    @Override
    public CaseInstanceQueryImpl caseInstanceBusinessKeyLikeIgnoreCase(String businessKeyLikeIgnoreCase) {
        if (businessKeyLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessKeyLikeIgnoreCase = businessKeyLikeIgnoreCase;
        } else {
            this.businessKeyLikeIgnoreCase = businessKeyLikeIgnoreCase;
        }
        return this;
    }
    
    @Override
    public CaseInstanceQueryImpl 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 CaseInstanceQueryImpl 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)