flowable/flowable-engine · error · FlowableIllegalArgumentException

categoryNotEquals is null

Error message

categoryNotEquals is null

What it means

ProcessDefinitionQueryImpl.processDefinitionCategoryNotEquals() excludes definitions whose category equals the given value, which must be non-null. A null exclusion value is meaningless as a filter, so Flowable throws FlowableIllegalArgumentException at call time. This is argument validation on the query builder, not a query execution failure.

Solutions

  1. Only call the method when a non-null exclusion value exists.
  2. Guard: if (categoryNotEquals != null) query.processDefinitionCategoryNotEquals(categoryNotEquals);
  3. Validate at the API boundary that exclusion filters are non-empty strings.
  4. Skip optional filters instead of passing null placeholders.

Example fix

// before
ProcessDefinitionQuery query = repositoryService.createProcessDefinitionQuery()
    .processDefinitionCategoryNotEquals(excludeCategory); // may be null

// after
ProcessDefinitionQuery query = repositoryService.createProcessDefinitionQuery();
if (excludeCategory != null) {
    query.processDefinitionCategoryNotEquals(excludeCategory);
}
Defensive patterns

Strategy: validation

Validate before calling

if (categoryNotEquals != null && !categoryNotEquals.isEmpty()) {
    query = repositoryService.createProcessDefinitionQuery().processDefinitionCategoryNotEquals(categoryNotEquals);
} else {
    query = repositoryService.createProcessDefinitionQuery();
}

Type guard

boolean hasExclusionValue(String v) {
    return v != null && !v.trim().isEmpty();
}

Try / catch

try {
    return repositoryService.createProcessDefinitionQuery().processDefinitionCategoryNotEquals(exclude).list();
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null categoryNotEquals value: {}", e.getMessage());
    throw new BadRequestException("categoryNotEquals must not be null");
}

Prevention

When it happens

Trigger: Calling processDefinitionCategoryNotEquals(null), typically when the exclusion value comes from an absent request parameter or an unset configuration property.

Common situations: Filter UIs where the 'exclude category' field was left blank; generic query-assembler code that calls every setter with values from a map containing null; refactor that replaced a default string with null.

Related errors

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessDefinitionQueryImpl.java:121

            throw new FlowableIllegalArgumentException("category is null");
        }
        this.category = category;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionCategoryLike(String categoryLike) {
        if (categoryLike == null) {
            throw new FlowableIllegalArgumentException("categoryLike is null");
        }
        this.categoryLike = categoryLike;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionCategoryNotEquals(String categoryNotEquals) {
        if (categoryNotEquals == null) {
            throw new FlowableIllegalArgumentException("categoryNotEquals is null");
        }
        this.categoryNotEquals = categoryNotEquals;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionName(String name) {
        if (name == null) {
            throw new FlowableIllegalArgumentException("name is null");
        }
        this.name = name;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionNameLike(String nameLike) {
        if (nameLike == null) {
            throw new FlowableIllegalArgumentException("nameLike is null");

View on GitHub (pinned to d6d39ce1c6)