Activiti/Activiti · error · ActivitiIllegalArgumentException

Business key is null

Error message

Business key is null

What it means

ProcessInstanceQueryImpl.processInstanceBusinessKey(String) throws ActivitiIllegalArgumentException when the businessKey argument is null. A null business key cannot be used as a query filter, so Activiti validates eagerly. This keeps query construction deterministic instead of failing later in the database layer.

Solutions

1. Validate the business key (null/blank) before building the query and return a clear client-side error if absent
2. Only add the filter when present: if (businessKey != null) query = query.processInstanceBusinessKey(businessKey);
3. Fix the upstream source (request validation, variable mapping) so the key is always populated when this path runs
4. Catch ActivitiIllegalArgumentException and translate it into your API's 400 response

Example fix

// before
if (businessKey != null) {
    query = query.processInstanceBusinessKey(businessKey);
}
// after
if (businessKey == null) {
    throw new BadRequestException("businessKey is required");
}
query = query.processInstanceBusinessKey(businessKey);

if (businessKey == null || businessKey.trim().isEmpty()) {
    throw new IllegalArgumentException("businessKey is required");
}

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

try {
    query.processInstanceBusinessKey(businessKey);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Business key is null")) {
        throw new BadRequestException("businessKey query parameter is required");
    }
    throw e;
}

When it happens

Trigger: Calling createProcessInstanceQuery().processInstanceBusinessKey(key) with key == null — usually a businessKey variable sourced from an unconfigured process variable, request parameter, or message header.

Common situations: REST controllers binding a missing query parameter to null; message-driven process starts where the correlation business key was absent; configuration where the business key mapping was never set.

Related errors

• event name is null
• event type is null
• Involved groups list is null or empty.
• job is null
• keyLike is null

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/54096ff7a84c5319. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:137

    public ProcessInstanceQuery processInstanceIds(Set<String> processInstanceIds) {
        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;
    }

    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;
    }

    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");
        }

        this.businessKey = businessKey;

View on GitHub (pinned to 56435b1a97)