flowable/flowable-engine · error · FlowableIllegalArgumentException

Business key is null

Error message

Business key is null

What it means

Flowable throws FlowableIllegalArgumentException when processInstanceBusinessKey(String) is called with a null businessKey. Query criteria setters in ProcessInstanceQueryImpl validate their arguments eagerly so that an invalid query fails at build time rather than at execution time with an obscure SQL error. Passing null here is always a bug because a null criterion means 'no filter', which the API forces you to express by simply not calling the setter.

Source

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

        if (processInstanceIds == null) {
            throw new FlowableIllegalArgumentException("Set of process instance ids is null");
        }
        if (processInstanceIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of process instance ids is empty");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processInstanceIds = processInstanceIds;
        } else {
            this.processInstanceIds = processInstanceIds;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceBusinessKey(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 ProcessInstanceQuery processInstanceBusinessKey(String businessKey, String processDefinitionKey) {
        if (businessKey == null) {
            throw new FlowableIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            throw new FlowableIllegalArgumentException("This method is not supported in an OR statement");
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Guard the call: only invoke processInstanceBusinessKey when the value is non-null, chaining conditionally on the query object.
2. Fix the upstream source so businessKey is populated (correct request mapping, form field, or entity load).
3. If an empty string is acceptable, normalize null to "" only if you truly want an equals-match on empty string.
4. If you intended no filtering, remove the call entirely instead of passing null.

Example fix

// before
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery()
    .processInstanceBusinessKey(businessKey);
// after
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery();
if (businessKey != null) {
    q = q.processInstanceBusinessKey(businessKey);
}

if (businessKey == null) {
    throw new IllegalArgumentException("businessKey must be provided before building the query");
}
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery().processInstanceBusinessKey(businessKey);

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

try {
    query.processInstanceBusinessKey(businessKey);
} catch (FlowableIllegalArgumentException e) {
    if (!e.getMessage().contains("Business key is null")) throw e;
    log.warn("No business key supplied; skipping business-key filter");
}

When it happens

Trigger: Calling processInstanceQuery.processInstanceBusinessKey(variableThatIsNull) — e.g. a method parameter, request parameter, or entity field that was never populated.

Common situations: Passing an optional HTTP query parameter straight through without a null check; a form/report field left empty; a refactored method whose businessKey argument became nullable; building queries generically from a map of criteria that contains a null value.

Related errors

• Business status 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/a7db21e106299fb4. Report an issue: GitHub.