flowable/flowable-engine · error · FlowableIllegalArgumentException

Business key is null

Error message

Business key is null

What it means

Flowable's CaseInstanceQueryImpl throws FlowableIllegalArgumentException when caseInstanceBusinessKey(String) is called with null. The business key is a user-defined correlation value stored on case instances; filtering by a null key is meaningless, so the engine validates the argument immediately. Pass a concrete business key string.

Solutions

1. Check the value for null before calling; only add the business-key criterion when a key is actually present
2. Return a client-side validation error if businessKey is a mandatory filter in your API
3. If any business key is acceptable, omit the criterion instead of passing null
4. Confirm you are reading the correct field from your DTO/request object

Example fix

// before
query.caseInstanceBusinessKey(request.getBusinessKey()); // may be null
// after
String businessKey = request.getBusinessKey();
if (businessKey != null) {
    query.caseInstanceBusinessKey(businessKey);
}

if (businessKey == null || businessKey.isBlank()) {
    throw new IllegalArgumentException("businessKey must be provided");
}
query.caseInstanceBusinessKey(businessKey);

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

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

When it happens

Trigger: Calling caseInstanceBusinessKey(null) directly; forwarding an unvalidated request parameter or DTO field that was not supplied; using a variable that was supposed to hold the business key but was never set.

Common situations: REST/search endpoints where the client omitted the businessKey parameter and the controller passes it straight into the query; config or form field not mapped; tests constructing queries programmatically with placeholder values; mixing up businessKey and businessStatus fields.

Related errors

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

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

Appendix: source

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

    }

    @Override
    public CaseInstanceQuery 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 CaseInstanceQueryImpl 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 CaseInstanceQueryImpl 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)