flowable/flowable-engine · error · FlowableIllegalArgumentException

Process instance id list is empty

Error message

Process instance id list is empty

What it means

TaskQueryImpl.processInstanceIdIn() rejects an empty collection because an empty SQL IN () is invalid and would silently match nothing. The library throws FlowableIllegalArgumentException so the caller handles the empty case explicitly.

Solutions

1. Check collection.isEmpty() before calling and return an empty result list early
2. Or omit the processInstanceIdIn filter if an empty set should mean 'no constraint' (verify business semantics)
3. For pagination-style IN queries, chunk and skip empty chunks

Example fix

// before
query.processInstanceIdIn(ids); // ids can be empty
// after
if (ids.isEmpty()) {
    return Collections.emptyList();
}
query.processInstanceIdIn(ids);

if (processInstanceIds == null || processInstanceIds.isEmpty()) {
    return Collections.emptyList(); // nothing to query
}
query.processInstanceIdIn(processInstanceIds);

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

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

When it happens

Trigger: Calling .processInstanceIdIn(Collections.emptyList()) or passing a collection filtered down to zero elements at runtime.

Common situations: Chaining queries where an earlier result set was empty; batch jobs with no work items in the current window.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Involved groups are empty
• Process category list is empty
• Task assignee list is empty
• Task category list is empty
• at least one of userId or groups must be provided

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

Appendix: source

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

    }

    @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;
    }

    @Override
    public TaskQueryImpl withoutProcessInstanceId() {
        if (orActive) {

View on GitHub (pinned to d6d39ce1c6)