flowable/flowable-engine · error · FlowableIllegalArgumentException

Set of case instance ids is empty

Error message

Set of case instance ids is empty

What it means

Flowable's PlanItemInstanceQuery.caseInstanceIds(Set<String>) throws FlowableIllegalArgumentException when the set is empty. An empty IN() clause would be invalid SQL and would semantically match nothing, so Flowable rejects it up front. Callers must either supply at least one id or omit the filter.

Solutions

1. Check set contents before querying: if empty, return an empty result immediately instead of executing the query
2. Skip the caseInstanceIds filter when the set is empty (though that changes semantics to 'all cases' — usually not intended)
3. Fix the upstream id-collection logic so it actually finds the case instances you expect

Example fix

// before
query.caseInstanceIds(collectedIds); // throws when collectedIds.isEmpty()

// after
if (collectedIds.isEmpty()) {
    return Collections.emptyList();
}
query.caseInstanceIds(collectedIds);

if (caseInstanceIds.isEmpty()) {
    return Collections.emptyList();
}
query.caseInstanceIds(caseInstanceIds);

boolean isNonEmpty(Set<String> s) { return s != null && !s.isEmpty(); }

try {
    query.caseInstanceIds(caseInstanceIds);
} catch (FlowableIllegalArgumentException e) {
    return Collections.emptyList();
}

When it happens

Trigger: Calling caseInstanceIds(new HashSet<>()) or caseInstanceIds(Collections.emptySet()) — common when the id set was populated by a prior query/list operation that returned zero results (e.g. filtering by a tenant or state that matches nothing).

Common situations: Downstream of another query whose result set was empty; batch jobs on fresh databases; REST clients sending an empty ids array which is mapped to an empty set.

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

• groupIds are empty
• ids is an empty collection
• Plan item definition types is empty
• activatedBefore is null
• assignee is null

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java:166

    public PlanItemInstanceQuery caseInstanceId(String caseInstanceId) {
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("Case instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseInstanceId = caseInstanceId;
        } else {
            this.caseInstanceId = caseInstanceId;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery caseInstanceIds(Set<String> caseInstanceIds) {
        if (caseInstanceIds == null) {
            throw new FlowableIllegalArgumentException("Set of case instance ids is null");
        }
        if (caseInstanceIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of case instance ids is empty");
        }

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

    @Override
    public PlanItemInstanceQuery stageInstanceId(String stageInstanceId) {
        if (stageInstanceId == null) {
            throw new FlowableIllegalArgumentException("Stage instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.stageInstanceId = stageInstanceId;
        } else {

View on GitHub (pinned to d6d39ce1c6)