flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition name is null

Error message

Case definition name is null

What it means

HistoricCaseInstanceQueryImpl.caseDefinitionName() validates that the name is non-null, throwing FlowableIllegalArgumentException otherwise. The engine fails fast rather than producing an invalid equality query.

Solutions

1. Call caseDefinitionName only when the name is set
2. Omit the filter for null/empty input
3. Use caseDefinitionNameLike (non-null required) for partial matches
4. Catch FlowableIllegalArgumentException to produce a clear validation response

Example fix

// before
query.caseDefinitionName(filter.getName());
// after
String name = filter.getName();
if (name != null && !name.isEmpty()) {
    query.caseDefinitionName(name);
}

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

boolean hasName = name instanceof String n && !n.isEmpty();

try {
    query.caseDefinitionName(name);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("Definition name must not be null", e);
}

When it happens

Trigger: Calling caseDefinitionName(null) or passing a name read from missing request/config data.

Common situations: Admin screens filtering historic cases by definition name where the field is left empty and null is forwarded.

Related errors

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

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

Appendix: source

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

    }
    
    @Override
    public HistoricCaseInstanceQueryImpl caseDefinitionCategoryLikeIgnoreCase(String caseDefinitionCategoryLikeIgnoreCase) {
        if (caseDefinitionCategoryLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("Case definition category is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionCategoryLikeIgnoreCase = caseDefinitionCategoryLikeIgnoreCase;
        } else {
            this.caseDefinitionCategoryLikeIgnoreCase = caseDefinitionCategoryLikeIgnoreCase;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQueryImpl caseDefinitionName(String caseDefinitionName) {
        if (caseDefinitionName == null) {
            throw new FlowableIllegalArgumentException("Case definition name is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionName = caseDefinitionName;
        } else {
            this.caseDefinitionName = caseDefinitionName;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQueryImpl caseDefinitionNameLike(String caseDefinitionNameLike) {
        if (caseDefinitionNameLike == null) {
            throw new FlowableIllegalArgumentException("Case definition name is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionNameLike = caseDefinitionNameLike;
        } else {
            this.caseDefinitionNameLike = caseDefinitionNameLike;

View on GitHub (pinned to d6d39ce1c6)