flowable/flowable-engine · error · ActivitiIllegalArgumentException

Business key is null

Error message

Business key is null

What it means

ExecutionQueryImpl.processInstanceBusinessKey(String) throws ActivitiIllegalArgumentException when the businessKey argument is null. The filter value must be a concrete non-null string for the query to be built. An empty string is allowed; only null is rejected.

Solutions

1. Pass a real business key string; check where the key originates and why it is null
2. Omit the business-key criterion if filtering by it is not intended
3. Add an explicit null check with a domain-specific error before calling the query API

Example fix

// before
List<Execution> execs = runtimeService.createExecutionQuery()
    .processInstanceBusinessKey(bizKey).list();
// after
if (bizKey == null) {
    throw new IllegalArgumentException("businessKey must be provided");
}
List<Execution> execs = runtimeService.createExecutionQuery()
    .processInstanceBusinessKey(bizKey).list();

if (businessKey != null) { query.processInstanceBusinessKey(businessKey); }

boolean hasKey = businessKey != null && !businessKey.trim().isEmpty();

try { q.processInstanceBusinessKey(key); } catch (ActivitiIllegalArgumentException e) { log.error("businessKey null: {}", e.getMessage()); }

When it happens

Trigger: Calling query.processInstanceBusinessKey(businessKey) with a null businessKey, e.g. an unset correlation key from configuration or a null field on a DTO.

Common situations: Lookups keyed by a business key (order id, document number) where the key was never assigned; upstream service returned null for the correlation identifier; test code constructing queries with placeholder nulls.

Related errors

• Execution id is null
• Parent id is null
• Process definition keys is null
• Process definition version is null
• Process instance id is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ExecutionQueryImpl.java:152

            throw new ActivitiIllegalArgumentException("Process definition version is null");
        }
        this.processDefinitionVersion = processDefinitionVersion;
        return this;
    }

    @Override
    public ExecutionQueryImpl processInstanceId(String processInstanceId) {
        if (processInstanceId == null) {
            throw new ActivitiIllegalArgumentException("Process instance id is null");
        }
        this.processInstanceId = processInstanceId;
        return this;
    }

    @Override
    public ExecutionQuery processInstanceBusinessKey(String businessKey) {
        if (businessKey == null) {
            throw new ActivitiIllegalArgumentException("Business key is null");
        }
        this.businessKey = businessKey;
        return this;
    }

    @Override
    public ExecutionQuery processInstanceBusinessKey(String processInstanceBusinessKey, boolean includeChildExecutions) {
        if (!includeChildExecutions) {
            return processInstanceBusinessKey(processInstanceBusinessKey);
        } else {
            if (processInstanceBusinessKey == null) {
                throw new ActivitiIllegalArgumentException("Business key is null");
            }
            this.businessKey = processInstanceBusinessKey;
            this.includeChildExecutionsWithBusinessKeyQuery = includeChildExecutions;
            return this;
        }
    }

View on GitHub (pinned to d6d39ce1c6)