What causes "Process instance id list is null" in flowable/flowable-engine?

Pass a non-null collection, e.g. List.of("pi-1","pi-2")

flowable/flowable-engine · error · FlowableIllegalArgumentException

Process instance id list is null

Error message

Process instance id list is null

What it means

TaskQueryImpl.processInstanceIdIn() requires a non-null collection of process instance ids to build the IN clause. A null collection cannot be translated to SQL, so the library throws FlowableIllegalArgumentException immediately.

Solutions

Pass a non-null collection, e.g. List.of("pi-1","pi-2")
Null-check the collection and skip the query or use an empty-result shortcut when absent
Fix the upstream producer to return an empty list rather than null

Example fix

// before
List<String> ids = fetchProcessInstanceIds(); // may return null
query.processInstanceIdIn(ids);
// after
List<String> ids = fetchProcessInstanceIds();
if (ids != null && !ids.isEmpty()) {
    query.processInstanceIdIn(ids);
} else {
    return Collections.emptyList();
}

Defensive patterns

Strategy: validation

Validate before calling

if (processInstanceIds == null) {
    throw new IllegalArgumentException("processInstanceIds must not be null");
}
query.processInstanceIdIn(processInstanceIds);

Type guard

boolean isQueryableIdList(Collection<String> c) { return c != null && !c.isEmpty() && c.stream().allMatch(Objects::nonNull); }

Try / catch

try {
    tasks = taskService.createTaskQuery().processInstanceIdIn(ids).list();
} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {
    log.warn("Invalid id list for query: {}", e.getMessage());
    tasks = Collections.emptyList();
}

Prevention

Never return null collections from producers; return empty lists
Use Collections.emptyList()/List.of() literals instead of null defaults
Validate collections at API boundaries (REST DTOs with @NotNull)

When it happens

Trigger: Calling taskService.createTaskQuery().processInstanceIdIn(null), often when the collection comes from an upstream method that returned null instead of an empty list.

Common situations: Aggregating ids from a previous query that returned null; deserializing request payloads where the ids field is absent.

Related errors

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

Appendix: source

Thrown at modules/flowable-task-service/src/main/java/org/flowable/task/service/impl/TaskQueryImpl.java:738

            this.withoutTenantId = true;
        }
        return this;
    }

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

    @Override
    public TaskQuery 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 (orActive) {
            currentOrQueryObject.processInstanceIds = processInstanceIds;
        } else {
            this.processInstanceIds = processInstanceIds;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)