flowable/flowable-engine · error · FlowableIllegalArgumentException

Business key is null

Error message

Business key is null

What it means

caseInstanceBusinessKey(String) throws FlowableIllegalArgumentException('Business key is null') when the business key argument is null. Business keys are optional query filters, so callers should simply skip the setter rather than pass null.

Source

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

            this.caseInstanceNameLike = nameLike;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceNameLikeIgnoreCase(String nameLikeIgnoreCase) {
        if (inOrStatement) {
            this.currentOrQueryObject.caseInstanceNameLikeIgnoreCase = nameLikeIgnoreCase;
        } else {
            this.caseInstanceNameLikeIgnoreCase = nameLikeIgnoreCase;
        }
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Only call caseInstanceBusinessKey when a non-null business key exists.
2. Substitute a like-query or skip filtering entirely if no key is available.
3. Catch FlowableIllegalArgumentException and map it to a 400 response.

Example fix

// before
query.caseInstanceBusinessKey(payload.get("businessKey"));
// after
String businessKey = payload.get("businessKey");
if (businessKey != null) {
    query.caseInstanceBusinessKey(businessKey);
}

if (businessKey == null) { throw new IllegalArgumentException("businessKey must not be null"); }
historicCaseInstanceQuery.caseInstanceBusinessKey(businessKey);

boolean hasBusinessKey(String key) { return key != null && !key.isEmpty(); }

try {
    query.caseInstanceBusinessKey(businessKey);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("businessKey must not be null", e);
}

When it happens

Trigger: Calling caseInstanceBusinessKey(null) with a business key sourced from an optional request parameter, header, or external record field.

Common situations: Search endpoints where businessKey is an optional filter; integration code copying fields from payloads with missing keys.

Related errors

• Case definition version is null
• Case instance id is null
• Case instance ids is null
• rootScopeId is null
• rootScopeIds is null or empty

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