What causes "Case instance ids is null" in flowable/flowable-engine?

Initialize the set (Collections.emptySet() / new HashSet<>()) instead of leaving it null, or skip the criterion call when null

flowable/flowable-engine · error · FlowableIllegalArgumentException

Case instance ids is null

Error message

Case instance ids is null

What it means

Flowable throws FlowableIllegalArgumentException from CaseInstanceQueryImpl.caseInstanceIds(Set<String>) when the id set is null. The set itself must be a non-null object (an empty set is allowed and simply matches nothing useful); null is rejected eagerly during query construction. Internal callers such as migrateCaseInstancesOfCaseDefinition rely on this to catch empty migration inputs early.

Solutions

Initialize the set (Collections.emptySet() / new HashSet<>()) instead of leaving it null, or skip the criterion call when null
In migration code, guard: if (instanceIds == null || instanceIds.isEmpty()) return early before building the query
Ensure prior lookups return empty collections, never null
Catch FlowableIllegalArgumentException in batch entry points and report which input was null

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if (ids == null || ids.isEmpty()) { return; } query.caseInstanceIds(ids);

Type guard

boolean hasIds = ids != null && !ids.isEmpty();

Try / catch

try { query.caseInstanceIds(instanceIds); } catch (FlowableIllegalArgumentException e) { log.warn("Null instance id set for migration"); return Collections.emptyList(); }

Prevention

Have collection-returning helpers return empty collections, never null
Initialize Set fields at declaration (new HashSet<>())
In batch/migration entry points, early-return on null/empty input collections

When it happens

Trigger: Calling createCaseInstanceQuery().caseInstanceIds(null), or migration APIs (migrateCaseInstancesOfCaseDefinition / batchMigrateCaseInstancesOfCaseDefinition) passing through a null instance-id collection collected from an empty/failed prior lookup.

Common situations: Batch operations where the ids collection was never initialized; result of a previous query returned null instead of an empty set; refactors changing a List to a Set without initializing it.

Related errors

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

Appendix: source

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

    @Override
    public CaseInstanceQueryImpl 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 CaseInstanceQueryImpl caseInstanceIds(Set<String> caseInstanceIds) {
        if (caseInstanceIds == null) {
            throw new FlowableIllegalArgumentException("Case instance ids is null");
        }

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

    @Override
    public CaseInstanceQuery caseInstanceName(String name) {
        if (name == null) {
            throw new FlowableIllegalArgumentException("Name is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.name = name;
        } else {

View on GitHub (pinned to d6d39ce1c6)