flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition category is null

Error message

Case definition category is null

What it means

HistoricCaseInstanceQueryImpl.caseDefinitionCategory() validates that the category is non-null before storing it, throwing FlowableIllegalArgumentException on null. Categories are optional filters, so callers should omit the call rather than pass null.

Solutions

1. Only call caseDefinitionCategory when a category is actually set
2. Omit the filter for null/empty input
3. Use caseDefinitionCategoryLike with a non-null pattern for partial matching
4. Catch FlowableIllegalArgumentException in generic query-building code

Example fix

// before
query.caseDefinitionCategory(tenantConfig.getCategory());
// after
String category = tenantConfig.getCategory();
if (category != null) {
    query.caseDefinitionCategory(category);
}

if (category != null && !category.isEmpty()) {
    query.caseDefinitionCategory(category);
}

boolean hasCategory = category instanceof String c && !c.isEmpty();

try {
    query.caseDefinitionCategory(category);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("Category must not be null", e);
}

When it happens

Trigger: Calling caseDefinitionCategory(null), or passing a category sourced from missing config/request data.

Common situations: Multi-tenant apps filtering by category where the tenant config lacks a category entry; UI filter bindings that default to null.

Related errors

• Case definition id is null
• Case definition ids is null
• Case definition key 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/eb2278ed86b6d055. Report an issue: GitHub.

Appendix: source

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

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

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

View on GitHub (pinned to d6d39ce1c6)