flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition category is null

Error message

Process definition category is null

What it means

FlowableIllegalArgumentException thrown by ExecutionQueryImpl.processDefinitionCategory when the category argument is null. Categories are optional filters, so Flowable requires you to omit the call rather than pass null. This fail-fast check keeps the persisted query state free of invalid values.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java:195

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

    @Override
    public ExecutionQuery processDefinitionCategory(String processDefinitionCategory) {
        if (processDefinitionCategory == null) {
            throw new FlowableIllegalArgumentException("Process definition category is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionCategory = processDefinitionCategory;
        } else {
            this.processDefinitionCategory = processDefinitionCategory;
        }
        return this;
    }
    
    @Override
    public ExecutionQuery processDefinitionCategoryLike(String processDefinitionCategoryLike) {
        if (processDefinitionCategoryLike == null) {
            throw new FlowableIllegalArgumentException("Process definition category is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionCategoryLike = processDefinitionCategoryLike;
        } else {
            this.processDefinitionCategoryLike = processDefinitionCategoryLike;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Only call processDefinitionCategory when the value is non-null.
2. Fix the source of the null: default the category in config or the requesting layer.
3. Use processDefinitionCategoryLike if you need pattern matching.
4. Remove the category filter to query all definitions.

Example fix

// before
query.processDefinitionCategory(filter.getCategory());

// after
if (filter.getCategory() != null) {
    query.processDefinitionCategory(filter.getCategory());
}

if (category != null) { query.processDefinitionCategory(category); }

boolean hasCategory = category != null;

try {
    query.processDefinitionCategory(category);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null category filter skipped");
}

When it happens

Trigger: Calling runtimeService.createExecutionQuery().processDefinitionCategory(null), or storing a null category into the query object in an or-statement branch.

Common situations: Category sourced from user input or configuration that is absent; model objects where category is an optional field mapped directly into the query.

Related errors

• Process definition name is null
• appsDefinitionIds is null
• category is null
• query is null
• parentScopeIds is null or empty

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