flowable/flowable-engine · error · FlowableIllegalArgumentException

Set of process definition ids is null

Error message

Set of process definition ids is null

What it means

ProcessInstanceQueryImpl.processDefinitionIds(Set<String>) throws FlowableIllegalArgumentException('Set of process definition ids is null') when the supplied set is null. The set feeds an IN(...) clause, which cannot be built from a null collection, so the method rejects null at query-construction time before the empty-set check and the assignment to the query or OR-query object.

Solutions

1. Null-check the set before calling processDefinitionIds and skip the filter when null
2. Initialize the collection to an empty (or populated) Set at declaration so it is never null
3. Fix the producer of the id set (permission lookup, config, deserialization) so it always returns a collection
4. Catch FlowableIllegalArgumentException and translate it into a client-side validation error

Example fix

// before
Set<String> ids = loadVisibleDefinitionIds(userId); // may return null
query.processDefinitionIds(ids);

// after
Set<String> ids = loadVisibleDefinitionIds(userId);
if (ids != null && !ids.isEmpty()) {
    query.processDefinitionIds(ids);
}

if (ids != null && !ids.isEmpty()) {
    query.processDefinitionIds(ids);
}

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

try {
    query.processDefinitionIds(ids);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("processDefinitionIds set must not be null or empty", e);
}

When it happens

Trigger: Calling .processDefinitionIds(null) — commonly when the set is built by a filter/aggregation step that returned null, a null field on a DTO, or an Optional unwrapped incorrectly.

Common situations: Batch dashboards where the list of visible definitions comes from user permissions and is null when permissions fail to load; code that conditionally collects ids but always calls the setter; deserialization of a request body missing the ids array.

Related errors

• executionIds is null
• groupId is null
• identityLinkType is null
• involvedGroups are null
• parentScopeIds is null or empty

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java:420

    @Override
    public ProcessInstanceQueryImpl processDefinitionId(String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new FlowableIllegalArgumentException("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 FlowableIllegalArgumentException("Set of process definition ids is null");
        }
        if (processDefinitionIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("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 FlowableIllegalArgumentException("Process definition key is null");
        }

View on GitHub (pinned to d6d39ce1c6)