flowable/flowable-engine · error · FlowableIllegalArgumentException

Set of process instance ids is null

Error message

Set of process instance ids is null

What it means

processInstanceIds(Set<String>) filters by a set of process instance ids. Flowable throws FlowableIllegalArgumentException when the set is null; callers must provide an actual Set. Used directly by the process-definition migration helpers, which construct this query to select instances to migrate.

Solutions

1. Pass a non-null Set of instance ids (may be validated non-empty before the call).
2. Initialize the collection to an empty Set at declaration so it's never null.
3. In migration flows, collect the ids first and abort with a clear message if none were loaded.

Example fix

// before
Set<String> ids = loadIds(); // may return null
migrationBuilder.migrateProcessInstancesOfProcessDefinition(defId, q -> q.processInstanceIds(ids));

// after
Set<String> ids = loadIds();
if (ids == null || ids.isEmpty()) {
    throw new IllegalStateException("no process instance ids supplied for migration");
}
migrationBuilder.migrateProcessInstancesOfProcessDefinition(defId, q -> q.processInstanceIds(ids));

if (ids == null) { throw new IllegalArgumentException("process instance ids set must not be null"); }

try { query.processInstanceIds(ids); } catch (FlowableIllegalArgumentException e) { throw new BadRequestException("processInstanceIds must be a non-null, non-empty set"); }

When it happens

Trigger: Calling processInstanceIds(null) directly, or via migrateProcessInstancesOfProcessDefinition / batchMigrateProcessInstancesOfProcessDefinition / validateMigrateProcessInstancesOfProcessDefinition when the instance-id list resolved to null.

Common situations: Migration tooling where the id list comes from a payload/file that failed to load; deserialization yielding null instead of an empty set; passing a List where a Set is expected via untyped APIs.

Related errors

• Process instance id is null
• activatedBefore is null
• activity tenant id is null
• after time is null
• after time is null

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

Appendix: source

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

    }

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

View on GitHub (pinned to d6d39ce1c6)