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

Pass a non-null Set (an empty set if nothing is selected, though verify desired semantics).

flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition ids is null

Error message

Case definition ids is null

What it means

CaseInstanceQueryImpl.caseDefinitionIds accepts a Set of case definition ids to filter on and rejects a null set with FlowableIllegalArgumentException. The query API distinguishes 'no filter' (don't call the method) from an explicit null argument, which is treated as a programming error.

Solutions

Pass a non-null Set (an empty set if nothing is selected, though verify desired semantics).
Only call caseDefinitionIds when the collection is non-null and non-empty.
Normalize null collections from request DTOs to null-safe conditional calls.

Example fix

// before
query.caseDefinitionIds(selectedIds).list();
// after
if (selectedIds != null && !selectedIds.isEmpty()) {
    query = query.caseDefinitionIds(selectedIds);
}
query.list();

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Initialize id collections to empty sets instead of null in DTOs.
Guard all collection-based query filters with null/empty checks.
Add a shared query-builder utility to enforce this pattern project-wide.

When it happens

Trigger: createCaseInstanceQuery().caseDefinitionIds(null), typically when the set comes from an optional input that was never populated. populateFromQuery callers propagate the same null through populateQuery.

Common situations: Multi-select definition filter in a UI where the user selected nothing and the collection is null instead of empty; deserialized request body omitting the ids field.

Related errors

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

Appendix: source

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

    @Override
    public CaseInstanceQueryImpl caseDefinitionId(String caseDefinitionId) {
        if (caseDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Case definition id is null");
        }

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

    @Override
    public CaseInstanceQueryImpl caseDefinitionIds(Set<String> caseDefinitionIds) {
        if (caseDefinitionIds == null) {
            throw new FlowableIllegalArgumentException("Case definition ids is null");
        }

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

    @Override
    public CaseInstanceQueryImpl caseDefinitionKey(String caseDefinitionKey) {
        if (caseDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Case definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionKey = caseDefinitionKey;
        } else {

View on GitHub (pinned to d6d39ce1c6)