flowable/flowable-engine · error · ActivitiIllegalArgumentException

Business key is null

Error message

Business key is null

What it means

processInstanceBusinessKey(businessKey) filters process instances by business key. It throws ActivitiIllegalArgumentException('Business key is null') for a null key, since a null business key cannot be used as an equality filter.

Solutions

1. Pass the real business key string used when the process was started
2. If the key is optional, build the query without the business-key filter instead of passing null
3. Validate the incoming reference (non-null, correct format) before querying
4. Catch ActivitiIllegalArgumentException and map it to a 400-style validation error

Example fix

// before
runtimeService.createProcessInstanceQuery()
    .processInstanceBusinessKey(orderRef.getBusinessKey()) // may be null
    .singleResult();
// after
if (orderRef.getBusinessKey() != null) {
    runtimeService.createProcessInstanceQuery()
        .processInstanceBusinessKey(orderRef.getBusinessKey())
        .singleResult();
}

if (businessKey == null) {
    throw new IllegalArgumentException("businessKey is required");
}
query.processInstanceBusinessKey(businessKey);

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

try {
    query.processInstanceBusinessKey(bk);
} catch (ActivitiIllegalArgumentException e) {
    throw new BadRequestException("businessKey is mandatory for correlation lookup");
}

When it happens

Trigger: Calling ProcessInstanceQuery.processInstanceBusinessKey(null), typically when the business key originates from an external reference (order id, document id) that was absent in the incoming request or message.

Common situations: Correlating external domain entities with workflow instances where the reference field is optional; message-driven resolvers that dropped the key attribute.

Related errors

• activity tenant id is null
• Deployment id is null
• deploymentCategory is null
• deploymentCategoryExclude is null
• deploymentName is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:129

        if (processInstanceIds == null) {
            throw new ActivitiIllegalArgumentException("Set of process instance ids is null");
        }
        if (processInstanceIds.isEmpty()) {
            throw new ActivitiIllegalArgumentException("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 ActivitiIllegalArgumentException("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 ActivitiIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            throw new ActivitiIllegalArgumentException("This method is not supported in an OR statement");
        }

View on GitHub (pinned to d6d39ce1c6)