flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process definition keys is null

Error message

Process definition keys is null

What it means

ExecutionQueryImpl.processDefinitionKeys throws ActivitiIllegalArgumentException when the processDefinitionKeys Set is null. The query expects a concrete set of definition keys to filter against; an empty set is permitted, null is not. This supports querying executions across multiple process definitions at once.

Solutions

1. Pass an initialized Set (empty set is fine if no keys are known)
2. Only call processDefinitionKeys when a non-null collection was collected
3. Coalesce null to Collections.emptySet() before invoking

Example fix

// before
query.processDefinitionKeys(allowedKeys);
// after
query.processDefinitionKeys(allowedKeys == null ? Collections.emptySet() : allowedKeys);

query.processDefinitionKeys(keys == null ? Collections.emptySet() : keys);

boolean hasKeys = keys != null;

try { q.processDefinitionKeys(keys); } catch (ActivitiIllegalArgumentException e) { q = q; /* proceed unfiltered */ }

When it happens

Trigger: Calling query.processDefinitionKeys(keys) where keys is null, commonly an unset collection built from configuration or from another service call.

Common situations: Dynamic whitelist filtering where the key list is optional; a null returned from a properties lookup instead of an empty set; InMemory logging/reporting jobs that assemble key sets at runtime.

Related errors

• Business key is null
• Execution id is null
• Parent id 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/f9ef494909782764. Report an issue: GitHub.

Appendix: source

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

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

    @Override
    public ExecutionQuery processDefinitionKeys(Set<String> processDefinitionKeys) {
        if (processDefinitionKeys == null) {
            throw new ActivitiIllegalArgumentException("Process definition keys is null");
        }
        this.processDefinitionKeys = processDefinitionKeys;
        return this;
    }

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

    @Override
    public ExecutionQueryImpl activityId(String activityId) {
        this.activityId = activityId;

View on GitHub (pinned to d6d39ce1c6)