flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition keys is null

Error message

Case definition keys is null

What it means

HistoricCaseInstanceQueryImpl.caseDefinitionKeys() throws FlowableIllegalArgumentException when the Set of case definition keys is null. The keys are used to build an SQL IN filter, so null is rejected before assignment (to the query or, in an or() block, to currentOrQueryObject). Note this check only tests null — an empty set is accepted here, unlike parentScopeIds.

Source

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

    }
    
    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceBusinessStatusLikeIgnoreCase(String businessStatusLikeIgnoreCase) {
        if (businessStatusLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("Business status is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessStatusLikeIgnoreCase = businessStatusLikeIgnoreCase;
        } else {
            this.businessStatusLikeIgnoreCase = businessStatusLikeIgnoreCase;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQueryImpl caseDefinitionKeys(Set<String> caseDefinitionKeys) {
        if (caseDefinitionKeys == null) {
            throw new FlowableIllegalArgumentException("Case definition keys is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionKeys = caseDefinitionKeys;
        } else {
            this.caseDefinitionKeys = caseDefinitionKeys;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQueryImpl excludeCaseDefinitionKeys(Set<String> excludeCaseDefinitionKeys) {
        if (excludeCaseDefinitionKeys == null) {
            throw new FlowableIllegalArgumentException("Case definition keys is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.excludeCaseDefinitionKeys = excludeCaseDefinitionKeys;
        } else {
            this.excludeCaseDefinitionKeys = excludeCaseDefinitionKeys;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a Set containing at least the desired case definition keys, e.g. Set.of("loanCase").
2. Skip the call when the key set is null to apply no definition-key filter.
3. Coalesce null to an empty Set only if you additionally check isEmpty() before calling.
4. Catch FlowableIllegalArgumentException around query assembly for user-supplied filters.

Example fix

// before
query.caseDefinitionKeys(definitionKeys);
// after
if (definitionKeys != null && !definitionKeys.isEmpty()) {
    query.caseDefinitionKeys(definitionKeys);
}

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

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

try {
    query.caseDefinitionKeys(keys);
} catch (FlowableIllegalArgumentException e) {
    throw new InvalidRequestException("caseDefinitionKeys must not be null");
}

When it happens

Trigger: Calling caseDefinitionKeys(null), e.g. when the keys collection comes from an Optional, a JSON body field, or another query's result that produced no value.

Common situations: Multi-tenant dashboards filtering historic cases by a set of case definition keys loaded from configuration; a missing config section yields null and is passed straight through.

Related errors

• query is null
• parentScopeIds is null or empty
• Business status is null
• tenant id is null
• variableNames is null or empty

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