flowable/flowable-engine · error · FlowableIllegalArgumentException

Set of case instance ids is null

Error message

Set of case instance ids is null

What it means

Flowable's PlanItemInstanceQuery.caseInstanceIds(Set<String>) throws FlowableIllegalArgumentException when the set itself is null. The batch variant expects a populated collection of case instance ids; passing null is rejected immediately at query-build time. An empty set is also rejected (separately) because it would produce invalid SQL IN clauses.

Solutions

1. Initialize and populate the Set with case instance ids before passing it
2. Guard the call: only invoke caseInstanceIds(ids) when ids != null (and not empty)
3. If there are no ids, skip the filter or short-circuit the query entirely rather than passing null

Example fix

// before
Set<String> ids = getCaseIds(); // may return null
query.caseInstanceIds(ids);

// after
Set<String> ids = getCaseIds();
if (ids != null && !ids.isEmpty()) {
    query.caseInstanceIds(ids);
}

if (caseInstanceIds != null && !caseInstanceIds.isEmpty()) {
    query.caseInstanceIds(caseInstanceIds);
}

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

try {
    query.caseInstanceIds(caseInstanceIds);
} catch (FlowableIllegalArgumentException e) {
    return Collections.emptyList(); // treat null/empty set as no matches
}

When it happens

Trigger: Calling caseInstanceIds(null) — typically when the Set was declared but never initialized, or a method returning a set of ids returned null on some code path.

Common situations: Bulk dashboard/reporting code assembling ids from another query whose result was null; refactoring from single-id to batch filtering without initializing the collection; deserialization of an empty request body yielding a null field.

Related errors

• activatedBefore is null
• assignee is null
• availableAfter is null
• availableBefore is null
• before time is null

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

Appendix: source

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

    }

    @Override
    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");
        }

View on GitHub (pinned to d6d39ce1c6)