flowable/flowable-engine · error · FlowableIllegalArgumentException

Set of process instance ids is null

Error message

Set of process instance ids is null

What it means

HistoricActivityInstanceQueryImpl.processInstanceIds(Set<String>) rejects a null set with FlowableIllegalArgumentException. The query needs an explicit, non-empty set of process instance ids to restrict activity instances to. Omit the call instead of passing null when the filter is not needed.

Source

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

    public long executeCount(CommandContext commandContext) {
        return CommandContextUtil.getHistoricActivityInstanceEntityManager(commandContext).findHistoricActivityInstanceCountByQueryCriteria(this);
    }

    @Override
    public List<HistoricActivityInstance> executeList(CommandContext commandContext) {
        return CommandContextUtil.getHistoricActivityInstanceEntityManager(commandContext).findHistoricActivityInstancesByQueryCriteria(this);
    }

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

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

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

    @Override
    public HistoricActivityInstanceQueryImpl processDefinitionId(String processDefinitionId) {
        this.processDefinitionId = processDefinitionId;
        return this;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Guard: only call processInstanceIds(ids) when ids != null
2. Default the collection to Collections.emptySet() upstream, then skip applying the filter if empty
3. If ids is null because the source query failed, fix the source to return an empty collection

Example fix

// before
Set<String> ids = getSelectedInstanceIds();
query.processInstanceIds(ids);

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

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

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

try {
    query.processInstanceIds(ids);
} catch (FlowableIllegalArgumentException e) {
    if (!e.getMessage().contains("Set of process instance ids is null")) throw e;
    // rebuild query without the id filter
}

When it happens

Trigger: Calling historicActivityInstanceQuery.processInstanceIds(null), or passing a set built from a null/absent collection (e.g. a null list converted via new HashSet<>(nullList) throwing, or a field that was never populated).

Common situations: Reporting screens where the id list comes from an optional request parameter; code paths where an upstream query returned null instead of an empty collection.

Related errors

• Set of called 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/6391432a4cb3162f. Report an issue: GitHub.