flowable/flowable-engine · error · FlowableIllegalArgumentException

Case instance ids is null

Error message

Case instance ids is null

What it means

Fluent-query guard in HistoricCaseInstanceQueryImpl.caseInstanceIds: the set of case instance ids used as an IN filter is null; the builder rejects it rather than generating an IN () clause or a NULL comparison.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java:327

    }

    @Override
    public HistoricCaseInstanceQueryImpl 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 HistoricCaseInstanceQueryImpl 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 HistoricCaseInstanceQueryImpl caseInstanceName(String name) {
        if (inOrStatement) {
            this.currentOrQueryObject.caseInstanceName = name;
        } else {
            this.caseInstanceName = name;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null Set, e.g. Collections.emptySet() when there are no ids.
2. Initialize the set at declaration so it is never null.
3. Catch FlowableIllegalArgumentException and return a validation error.

Example fix

// before
query.caseInstanceIds(idsMap.get("ids")); // null when key missing
// after
Set<String> ids = idsMap.getOrDefault("ids", Collections.emptySet());
query.caseInstanceIds(ids);

if (caseInstanceIds == null) { throw new IllegalArgumentException("caseInstanceIds must not be null"); }
historicCaseInstanceQuery.caseInstanceIds(caseInstanceIds);

boolean isValidIdSet(Set<String> ids) { return ids != null; }

try {
    query.caseInstanceIds(ids);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("caseInstanceIds must not be null", e);
}

When it happens

Trigger: Calling caseInstanceIds(null), typically because an upstream collection was never instantiated or a lookup returned null instead of an empty set.

Common situations: Collecting ids from a previous query result that was null; deserializing JSON where the ids array is missing.

Related errors

• Case definition version is null
• Case instance id is null
• Business key is null
• rootScopeId is null
• rootScopeIds is null or empty

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