Activiti/Activiti · error · ActivitiIllegalArgumentException

Set of process definition keys is null

Error message

Set of process definition keys is null

What it means

ProcessInstanceQuery.processDefinitionKeys(Set) throws ActivitiIllegalArgumentException when the keys set is null. Like the other collection filters, the engine requires a real set to build the SQL IN clause.

Solutions

1. Initialize to an empty set and guard with a null/isEmpty check before calling
2. Only apply the filter when keys were collected
3. Return an early result or unfiltered query depending on intended semantics

Example fix

// before
query.processDefinitionKeys(processKeys);
// after
if (processKeys != null && !processKeys.isEmpty()) {
    query.processDefinitionKeys(processKeys);
}

if (keys == null) { throw new IllegalArgumentException("processDefinitionKeys must be initialized"); }
if (!keys.isEmpty()) { query.processDefinitionKeys(keys); }

boolean isNonEmptySet(Set<String> s) { return s != null && !s.isEmpty(); }

try {
    query.processDefinitionKeys(keys);
} catch (ActivitiIllegalArgumentException e) {
    logger.warn("Invalid key set: {}", e.getMessage());
}

When it happens

Trigger: Calling .processDefinitionKeys(null), e.g. an uninitialized field or a lookup that returned null instead of a set.

Common situations: Multi-tenant filters built from nullable tenant metadata; refactored code paths that lost initialization; deserialized DTOs with null collections.

Related errors

• Involved user is null
• key is null
• name is null
• Process definition id is null
• Process definition key is null

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

Appendix: source

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

    }

    public ProcessInstanceQueryImpl processDefinitionKey(String processDefinitionKey) {
        if (processDefinitionKey == null) {
            throw new ActivitiIllegalArgumentException("Process definition key is null");
        }

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

    @Override
    public ProcessInstanceQuery processDefinitionKeys(Set<String> processDefinitionKeys) {
        if (processDefinitionKeys == null) {
            throw new ActivitiIllegalArgumentException("Set of process definition keys is null");
        }
        if (processDefinitionKeys.isEmpty()) {
            throw new ActivitiIllegalArgumentException("Set of process definition keys is empty");
        }

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

    public ProcessInstanceQueryImpl deploymentId(String deploymentId) {
        if (inOrStatement) {
            this.currentOrQueryObject.deploymentId = deploymentId;
        } else {
            this.deploymentId = deploymentId;

View on GitHub (pinned to 56435b1a97)