flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition key is null

Error message

Case definition key is null

What it means

CaseInstanceQueryImpl.caseDefinitionKey filters case instances by the case definition's key and validates the argument, throwing FlowableIllegalArgumentException when null. Null is rejected rather than treated as 'no filter' to catch accidental API misuse.

Solutions

1. Pass the actual case definition key string.
2. Call caseDefinitionKey only when the key is non-null.
3. Validate the input at the boundary before building the query.

Example fix

// before
query.caseDefinitionKey(params.getKey()).list();
// after
if (params.getKey() != null) {
    query = query.caseDefinitionKey(params.getKey());
}
query.list();

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

When it happens

Trigger: createCaseInstanceQuery().caseDefinitionKey(null), e.g. when the key is read from config/request and is absent.

Common situations: Filter forms where the definition key dropdown has no default value; refactored code that removed the literal key but kept the call.

Related errors

• Case definition category is null
• Case definition id is null
• activatedBefore is null
• assignee is null
• availableAfter is null

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

Appendix: source

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

    @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 {
            this.caseDefinitionKey = caseDefinitionKey;
        }
        return this;
    }
    
    @Override
    public CaseInstanceQueryImpl 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)