flowable/flowable-engine · error · FlowableIllegalArgumentException

Set of called process instance ids is null

Error message

Set of called process instance ids is null

What it means

HistoricActivityInstanceQueryImpl.calledProcessInstanceIds(Set<String>) rejects a null set with FlowableIllegalArgumentException. This filter restricts activity instances to those of called (sub) process instances with the given ids. Null means the criterion is undefined, which Flowable does not accept.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/HistoricActivityInstanceQueryImpl.java:163

        this.finishedAfter = date;
        return this;
    }
    @Override
    public HistoricActivityInstanceQueryImpl finishedBefore(Date date) {
        this.finishedBefore = date;
        return this;
    }

    @Override
    public HistoricActivityInstanceQuery activityTypes(Set<String> activityTypes) {
        this.activityTypes=activityTypes;
        return this;
    }

    @Override
    public HistoricActivityInstanceQuery calledProcessInstanceIds(Set<String> calledProcessInstanceIds) {
        if (calledProcessInstanceIds == null) {
            throw new FlowableIllegalArgumentException("Set of called process instance ids is null");
        }
        if (calledProcessInstanceIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of called process instance ids is empty");
        }
        this.calledProcessInstanceIds = calledProcessInstanceIds;
        return this;
    }

    @Override
    public HistoricActivityInstanceQueryImpl taskAssignee(String assignee) {
        this.assignee = assignee;
        return this;
    }

    @Override
    public HistoricActivityInstanceQuery taskCompletedBy(String userId) {
        this.completedBy = userId;
        return this;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Guard the call with a null check and skip the filter when the set is absent
2. Ensure the id collection step always returns an empty set rather than null
3. Use the singular calledProcessInstanceId(String) if only one id is known and it may be absent

Example fix

// before
Set<String> calledIds = hierarchyLookup.getSubProcessIds();
query.calledProcessInstanceIds(calledIds);

// after
Set<String> calledIds = hierarchyLookup.getSubProcessIds();
if (calledIds != null) {
    query.calledProcessInstanceIds(calledIds);
}

if (calledIds != null && !calledIds.isEmpty()) {
    query.calledProcessInstanceIds(calledIds);
}

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

try {
    query.calledProcessInstanceIds(calledIds);
} catch (FlowableIllegalArgumentException e) {
    if (!e.getMessage().contains("called process instance ids is null")) throw e;
    // rebuild query without the called-ids filter
}

When it happens

Trigger: Calling query.calledProcessInstanceIds(null), or passing a set derived from an absent/optional collection of sub-process instance ids (uninitialized field, null map lookup).

Common situations: Analyzing call-activity hierarchies where the sub-process ids are collected from a previous query that returned null; optional drill-down filters in monitoring tools.

Related errors

• Set of process instance ids is null
• variableNames is null or empty
• planItemDefinitionId is null
• planItemDefinitionIds is null
• involvedUser is null

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