flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition key is null

Error message

Case definition key is null

What it means

HistoricCaseInstanceQueryImpl.caseDefinitionKey() validates that the case definition key is not null before storing it. Null keys would create an invalid equality predicate, so Flowable throws FlowableIllegalArgumentException eagerly.

Solutions

1. Resolve a valid key first, or skip the call when the key is unknown
2. Use caseDefinitionKeyLike for partial matching only with a non-null value
3. Add a null guard around optional filters
4. Catch FlowableIllegalArgumentException for user-facing validation errors

Example fix

// before
query.caseDefinitionKey(params.get("caseKey"));
// after
String key = params.get("caseKey");
if (key != null) {
    query.caseDefinitionKey(key);
}

if (caseDefinitionKey != null) {
    query.caseDefinitionKey(caseDefinitionKey);
}

boolean hasKey = key != null && !key.isBlank();

try {
    query.caseDefinitionKey(key);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("Case definition key must not be null", e);
}

When it happens

Trigger: Calling caseDefinitionKey(null) or forwarding an unresolved key, e.g. a request parameter, path variable, or config entry that is absent.

Common situations: Building dynamic historic-case queries in services where the key comes from optional user input; copying code between process (BPMN) and case (CMMN) query APIs.

Related errors

• Case definition category is null
• Case definition id is null
• Case definition ids is null
• Case definition name is null
• after time is null

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

Appendix: source

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

    }

    @Override
    public HistoricCaseInstanceQuery 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 HistoricCaseInstanceQueryImpl caseDefinitionKey(String caseDefinitionKey) {
        if (caseDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Case definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionKey = caseDefinitionKey;
        } else {
            this.caseDefinitionKey = caseDefinitionKey;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQueryImpl caseDefinitionKeyLike(String caseDefinitionKeyLike) {
        if (caseDefinitionKeyLike == null) {
            throw new FlowableIllegalArgumentException("Case definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionKeyLike = caseDefinitionKeyLike;
        } else {
            this.caseDefinitionKeyLike = caseDefinitionKeyLike;

View on GitHub (pinned to d6d39ce1c6)