flowable/flowable-engine · error · FlowableIllegalArgumentException

Business status is null

Error message

Business status is null

What it means

processInstanceBusinessStatus(String) throws FlowableIllegalArgumentException when businessStatus is null. Query criteria setters validate their argument so the query fails fast at build time. A null criterion must be expressed by omitting the setter call, not by passing null.

Source

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

            this.businessKeyLike = businessKeyLike;
        }
        return this;
    }
    
    @Override
    public ProcessInstanceQuery processInstanceBusinessKeyLikeIgnoreCase(String businessKeyLikeIgnoreCase) {
        if (inOrStatement) {
            this.currentOrQueryObject.businessKeyLikeIgnoreCase = businessKeyLikeIgnoreCase;
        } else {
            this.businessKeyLikeIgnoreCase = businessKeyLikeIgnoreCase;
        }
        return this;
    }
    
    @Override
    public ProcessInstanceQuery processInstanceBusinessStatus(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 ProcessInstanceQuery processInstanceBusinessStatusLike(String businessStatusLike) {
        if (inOrStatement) {
            this.currentOrQueryObject.businessStatusLike = businessStatusLike;
        } else {
            this.businessStatusLike = businessStatusLike;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Only call processInstanceBusinessStatus when the value is non-null, building the query conditionally.
2. Populate the business status upstream (ensure startProcessInstanceBy... businessStatus or the runtime data actually sets it).
3. If no filtering is intended, drop the call.

Example fix

// before
query.processInstanceBusinessStatus(businessStatus);
// after
if (businessStatus != null) {
    query.processInstanceBusinessStatus(businessStatus);
}

if (businessStatus == null) {
    throw new IllegalArgumentException("businessStatus must be non-null when filtering by business status");
}

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

try {
    query.processInstanceBusinessStatus(businessStatus);
} catch (FlowableIllegalArgumentException e) {
    if (!e.getMessage().contains("Business status is null")) throw e;
    log.debug("businessStatus absent; query unfiltered by status");
}

When it happens

Trigger: Calling processInstanceBusinessStatus(null), typically with a variable or request parameter that was never set.

Common situations: An optional filter field in a search UI passed straight through; a process variable/entity attribute that is null because the business status was never recorded; migrating code where the field was added later and older data lacks it.

Related errors

• Business key is null
• Process definition category is null
• Provided job id is null
• categoryLike is null
• categoryNotEquals is null

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