flowable/flowable-engine · error · FlowableIllegalArgumentException

Process instance id list is null

Error message

Process instance id list is null

What it means

HistoricTaskInstanceQueryImpl.processInstanceIdIn(Collection<String>) validates its argument before storing it on the query. Passing a null collection immediately throws FlowableIllegalArgumentException('Process instance id list is null'). The query builder fails fast so the invalid predicate never reaches the SQL layer.

Solutions

1. Guard the call: only invoke processInstanceIdIn when the collection is non-null.
2. Replace null with an empty check upstream — decide whether to skip the predicate (no filter) or handle 'no instances' without querying.
3. If the source may return null, normalize it at the boundary (e.g. Collections.emptyList()) and branch on emptiness instead.

Example fix

// before
List<String> ids = lookupProcessInstanceIds(); // may be null
query.processInstanceIdIn(ids); // FlowableIllegalArgumentException

// after
if (ids != null && !ids.isEmpty()) {
    query.processInstanceIdIn(ids);
}

if (processInstanceIds == null) { processInstanceIds = Collections.emptyList(); }

boolean isUsableIdList(Collection<String> c) { return c != null && !c.isEmpty(); }

try {
    query.processInstanceIdIn(ids);
} catch (FlowableIllegalArgumentException e) {
    // fall back to unfiltered query or return empty result
}

When it happens

Trigger: Calling historicTaskInstanceQuery().processInstanceIdIn(null); typically when the collection is the result of an earlier lookup that returned null (uninitialized variable, absent map value).

Common situations: Building dynamic filters where processInstanceIds comes from an upstream API/service returning null when no instances apply; forgetting to initialize a list field; reflection-driven query construction passing null.

Related errors

• Process category list is null
• appsDefinitionIds is null
• Business status is null
• callback type is null
• callbackIds is null or empty

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

Appendix: source

Thrown at modules/flowable-task-service/src/main/java/org/flowable/task/service/impl/HistoricTaskInstanceQueryImpl.java:301

                    .addAll(variableServiceConfiguration.getHistoricVariableInstanceEntityManager()
                            .findHistoricalVariableInstancesByTaskId(task.getId()));
        }
    }

    @Override
    public HistoricTaskInstanceQueryImpl processInstanceId(String processInstanceId) {
        if (inOrStatement) {
            this.currentOrQueryObject.processInstanceId = processInstanceId;
        } else {
            this.processInstanceId = processInstanceId;
        }
        return this;
    }

    @Override
    public HistoricTaskInstanceQueryImpl processInstanceIdIn(Collection<String> processInstanceIds) {
        if (processInstanceIds == null) {
            throw new FlowableIllegalArgumentException("Process instance id list is null");
        }
        if (processInstanceIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Process instance id list is empty");
        }
        for (String processInstanceId : processInstanceIds) {
            if (processInstanceId == null) {
                throw new FlowableIllegalArgumentException("None of the given process instance ids can be null");
            }
        }

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

View on GitHub (pinned to d6d39ce1c6)