flowable/flowable-engine · error · FlowableIllegalArgumentException

category is null

Error message

category is null

What it means

ModelQueryImpl.modelCategory sets an exact-match filter on the model's category. A null filter is rejected with FlowableIllegalArgumentException because a null would be indistinguishable from 'no filter applied'; the API requires callers to simply not call modelCategory when they do not want to filter by category.

Solutions

1. Only call modelCategory when the value is non-null: build the query conditionally
2. Replace null with an explicit sentinel you intend to match (models without category need a different API)
3. Validate/normalize request input before constructing the query
4. Use modelCategoryLike with a non-null pattern only if a partial match is actually wanted

Example fix

// before
ModelQuery query = repositoryService.createModelQuery()
    .modelCategory(request.getCategory()); // may be null
// after
ModelQuery query = repositoryService.createModelQuery();
if (request.getCategory() != null) {
    query = query.modelCategory(request.getCategory());
}

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

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

try {
    List<Model> models = query.modelCategory(category).list();
} catch (FlowableIllegalArgumentException e) {
    log.warn("Bad model query filter: {}", e.getMessage());
}

When it happens

Trigger: Calling repositoryService.createModelQuery().modelCategory(category) with a null category, usually when the category comes from a request parameter, database field, or variable that is null.

Common situations: REST endpoints forwarding user-supplied category filters straight into the query; UIs with optional category fields; deserialization producing null for absent JSON fields.

Related errors

• activatedBefore is null
• activity tenant id is null
• after time is null
• categoryLike is null
• categoryNotEquals is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ModelQueryImpl.java:69

    public ModelQueryImpl(CommandContext commandContext) {
        super(commandContext);
    }

    public ModelQueryImpl(CommandExecutor commandExecutor) {
        super(commandExecutor);
    }

    @Override
    public ModelQueryImpl modelId(String modelId) {
        this.id = modelId;
        return this;
    }

    @Override
    public ModelQueryImpl modelCategory(String category) {
        if (category == null) {
            throw new FlowableIllegalArgumentException("category is null");
        }
        this.category = category;
        return this;
    }

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

    @Override
    public ModelQueryImpl modelCategoryNotEquals(String categoryNotEquals) {
        if (categoryNotEquals == null) {
            throw new FlowableIllegalArgumentException("categoryNotEquals is null");

View on GitHub (pinned to d6d39ce1c6)