flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition name is null

Error message

Case definition name is null

What it means

Flowable throws FlowableIllegalArgumentException from CaseInstanceQueryImpl.caseDefinitionName(String) when the supplied case definition name is null. Query criteria methods in Flowable validate arguments eagerly so that a malformed query fails immediately at build time rather than producing an invalid SQL query or misleading empty results at execution time. A null name is never a valid filter value; omit the call entirely instead.

Solutions

1. Do not call caseDefinitionName when the value is null — build the query conditionally: if (name != null) query.caseDefinitionName(name)
2. Default the input to a non-null sentinel before calling (e.g. name == null ? "" : name) only if an empty-ish match is truly intended
3. Use caseDefinitionKey or another criterion if the name is unknown and you need a valid filter
4. Wrap the query building in a FlowableIllegalArgumentException catch to surface a friendlier message to API callers

Example fix

// before
String name = request.getParameter("definitionName"); // may be null
CaseInstanceQuery q = runtimeService.createCaseInstanceQuery().caseDefinitionName(name);
// after
String name = request.getParameter("definitionName");
CaseInstanceQuery q = runtimeService.createCaseInstanceQuery();
if (name != null) {
    q.caseDefinitionName(name);
}

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

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

try { query.caseDefinitionName(name); } catch (FlowableIllegalArgumentException e) { log.warn("Invalid query argument: {}", e.getMessage()); throw new BadRequestException(e.getMessage()); }

When it happens

Trigger: Calling cmmnRuntimeService.createCaseInstanceQuery().caseDefinitionName(null) directly, or passing a variable that is null (e.g. an unresolved config value, missing request parameter, or unset field) into caseDefinitionName().

Common situations: REST/API query endpoints where the client omitted the definitionName filter and the code forwards the raw null; property/config lookups returning null; refactors that changed the default value of a name variable from empty string to null.

Related errors

• activatedBefore is null
• assignee is null
• availableAfter is null
• availableBefore is null
• before time is null

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

Appendix: source

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

    
    @Override
    public CaseInstanceQueryImpl 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 CaseInstanceQueryImpl 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 CaseInstanceQueryImpl caseDefinitionNameLike(String caseDefinitionNameLike) {
        if (caseDefinitionNameLike == null) {
            throw new FlowableIllegalArgumentException("Case definition name is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionNameLike = caseDefinitionNameLike;

View on GitHub (pinned to d6d39ce1c6)