flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition keys is null

Error message

Case definition keys is null

What it means

Flowable's CaseInstanceQueryImpl throws FlowableIllegalArgumentException when caseDefinitionKeys(Set<String>) is called with a null set. Unlike some sibling methods, this check rejects only null (an empty set is accepted), filtering case instances by their case definition key (the 'key' attribute of the CMMN case model). Pass a non-null set of definition keys.

Source

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

    }
    
    @Override
    public CaseInstanceQueryImpl 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 CaseInstanceQueryImpl 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 CaseInstanceQueryImpl 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. Initialize the set before calling (Collections.emptySet() is acceptable here; only null is rejected)
2. Only add the criterion when the set reference is non-null
3. Fix the configuration/lookup that should have supplied the definition keys
4. Use caseDefinitionKey(String) if you only have a single key

Example fix

// before
query.caseDefinitionKeys(allowedKeys); // allowedKeys may be null
// after
if (allowedKeys != null) {
    query.caseDefinitionKeys(allowedKeys);
}

if (caseDefinitionKeys == null) {
    return query; // null is rejected; empty set is allowed
}
query.caseDefinitionKeys(caseDefinitionKeys);

boolean hasCaseDefinitionKeys(Set<String> keys) {
    return keys != null;
}

try {
    query.caseDefinitionKeys(caseDefinitionKeys);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null case definition keys: {}", e.getMessage());
    throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "caseDefinitionKeys must not be null");
}

When it happens

Trigger: Calling caseDefinitionKeys(null); passing a set field from configuration/DTO that was never populated; collecting definition keys from a repository lookup that returned null instead of an empty set.

Common situations: Multi-tenant deployments where the allowed case definition keys come from tenant config that is missing; refactoring from caseDefinitionKey (single) to caseDefinitionKeys (plural) with an uninitialized collection; Spring bean wiring where the Set property has no default.

Related errors

• name is null
• nameLike is null
• nameLikeIgnoreCase is null
• id is null
• ids are null

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