flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition category is null

Error message

Process definition category is null

What it means

processDefinitionCategory(String) throws FlowableIllegalArgumentException 'Process definition category is null' when the category argument is null. The category filter (set on deployed process definitions) is validated eagerly so bad queries fail at construction. Pass an empty string only if you truly mean category equals empty; otherwise omit the call.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java:308

            this.tenantIdLikeIgnoreCase = tenantIdLikeIgnoreCase;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceWithoutTenantId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutTenantId = true;
        } else {
            this.withoutTenantId = true;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery 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 ProcessInstanceQuery processDefinitionCategoryLike(String processDefinitionCategoryLike) {
        if (processDefinitionCategoryLike == null) {
            throw new FlowableIllegalArgumentException("Process definition category is null");
        }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Call the setter only when the category is non-null.
2. Fix configuration so a valid category is supplied (e.g. default category in application config).
3. Remove the criterion when filtering by category is not needed.

Example fix

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

if (processDefinitionCategory == null) {
    throw new IllegalArgumentException("processDefinitionCategory must be non-null when filtering by category");
}

boolean hasCategory(String s) { return s != null && !s.trim().isEmpty(); }

try {
    query.processDefinitionCategory(category);
} catch (FlowableIllegalArgumentException e) {
    if (!e.getMessage().contains("category is null")) throw e;
    log.warn("No category configured; removing category filter");
}

When it happens

Trigger: Calling processDefinitionCategory(null), often with a category read from configuration, a deployment descriptor, or an optional request filter.

Common situations: Config property for the category missing (null placeholder); optional filter field in a UI passed unguarded; refactoring where the category constant was removed.

Related errors

• Business key is null
• Business status is null
• Provided job id is null
• categoryLike is null
• categoryNotEquals is null

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