flowable/flowable-engine · error · ActivitiIllegalArgumentException

Set of process instance ids is null

Error message

Set of process instance ids is null

What it means

processInstanceIds(Set) filters by an explicit set of process instance ids. It throws ActivitiIllegalArgumentException('Set of process instance ids is null') when the set itself is null; emptiness is checked separately by the next guard.

Source

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

    }

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

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

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null, non-empty Set<String> of process instance ids
2. Initialize the set with an empty default at construction and check isEmpty() before querying
3. Skip the query entirely when no ids were supplied and return an empty result to the caller
4. Catch ActivitiIllegalArgumentException as an input-validation failure

Example fix

// before
query.processInstanceIds(requestedIds == null ? null : new HashSet<>(requestedIds));
// after
if (requestedIds != null && !requestedIds.isEmpty()) {
    query.processInstanceIds(new HashSet<>(requestedIds));
}

if (ids == null) {
    throw new IllegalArgumentException("processInstanceIds set must not be null");
}
if (ids.isEmpty()) {
    return Collections.emptyList();
}
query.processInstanceIds(new HashSet<>(ids));

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

try {
    query.processInstanceIds(ids);
} catch (ActivitiIllegalArgumentException e) {
    throw new BadRequestException("A non-empty set of process instance ids is required");
}

When it happens

Trigger: Calling ProcessInstanceQuery.processInstanceIds(null), commonly when a caller-supplied id list was mapped to a Set that stayed null (e.g. empty request body, null-split of a CSV parameter).

Common situations: Batch dashboards built from user-supplied id lists; integration code where the id collection failed to load before the query was issued.

Related errors

• Process instance id is null
• Deployment id is null
• deploymentName is null
• deploymentNameLike is null
• deploymentCategory is null

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