flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process instance id list is empty

Error message

Process instance id list is empty

What it means

TaskQueryImpl.processInstanceIdIn(List<String>) throws ActivitiIllegalArgumentException when the processInstanceIds list is empty. An empty IN list would yield invalid SQL (IN ()), so the engine rejects it eagerly when the query is built rather than at execution time.

Solutions

1. Check isEmpty() before calling processInstanceIdIn and short-circuit to an empty result instead of querying.
2. Centralize the null/empty guard in a query helper shared by all task queries.
3. Catch ActivitiIllegalArgumentException and translate it into 'no process instances selected' for the client.

Example fix

// before
taskQuery.processInstanceIdIn(instanceIds); // may be empty

// after
if (instanceIds == null || instanceIds.isEmpty()) {
    return Collections.emptyList();
}
taskQuery.processInstanceIdIn(instanceIds);

if (processInstanceIds == null || processInstanceIds.isEmpty()) {
    return Collections.emptyList();
}
taskQuery.processInstanceIdIn(processInstanceIds);

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

try {
    return taskQuery.processInstanceIdIn(ids).list();
} catch (ActivitiIllegalArgumentException e) {
    log.warn("Empty id list rejected: {}", e.getMessage());
    return Collections.emptyList();
}

When it happens

Trigger: Calling taskQuery.processInstanceIdIn(new ArrayList<>()) or passing a filtered collection with zero remaining ids.

Common situations: No process instances matched a preceding lookup (e.g. all completed/canceled), so the id list arrives empty; business code then builds the query unconditionally.

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

• Candidate group list is empty
• Candidate group list is null
• None of the given process instance ids can be null
• Process category list is empty
• Process category list is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/TaskQueryImpl.java:623

    }

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

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

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

    @Override
    public TaskQueryImpl processInstanceBusinessKey(String processInstanceBusinessKey) {
        if (orActive) {

View on GitHub (pinned to d6d39ce1c6)