flowable/flowable-engine · error · ActivitiIllegalArgumentException

Set of process definition ids is null

Error message

Set of process definition ids is null

What it means

ProcessInstanceQueryImpl.processDefinitionIds(Set<String>) throws ActivitiIllegalArgumentException when the processDefinitionIds set itself is null (a separate error exists for an empty set). The IN-style filter requires a concrete, non-empty collection of ids. This eager validation prevents building queries whose SQL would be malformed or unfiltered.

Source

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

    @Override
    public ProcessInstanceQueryImpl processDefinitionId(String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new ActivitiIllegalArgumentException("Process definition id is null");
        }

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

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

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Default to Collections.emptySet() and skip the filter when empty, or guarantee the set is populated before calling.
2. Null-check any method returning a set of ids before passing it into the query.
3. Normalize incoming JSON/dto collections (null -> empty -> no filter) before query construction.
4. Catch ActivitiIllegalArgumentException around query building to produce a descriptive validation error.

Example fix

// before
query.processDefinitionIds(allowedIds); // may be null
// after
if (allowedIds != null && !allowedIds.isEmpty()) {
    query = query.processDefinitionIds(allowedIds);
}

if (ids == null || ids.isEmpty()) {
    // either return empty result or skip the filter
    return Collections.emptyList(); // if ids represent access restrictions
}
query = query.processDefinitionIds(ids);

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

try {
    result = query.processDefinitionIds(ids).list();
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("process definition ids is null")) {
        throw new BadRequestException("processDefinitionIds set must not be null");
    }
    throw e;
}

When it happens

Trigger: Calling .processDefinitionIds(null) — typically a Set field initialized but never populated, a null return from a lookup method, or a deserialized filter DTO with a missing list.

Common situations: Collections from optional groupings (tenant lookups, user-visible definitions) returning null when no results; JSON payloads omitting an ids array; pre-Java-9 Optional misuse returning raw null.

Related errors

• Set of process definition keys is null
• process instance tenant id is null
• Process definition category is null
• Process definition name is null
• Process definition version is null

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