flowable/flowable-engine · error · ActivitiIllegalArgumentException

category is null

Error message

category is null

What it means

ProcessDefinitionQueryImpl.processDefinitionCategory(String) filters process definitions by their exact category (the BPMN targetNamespace/category metadata). Flowable throws ActivitiIllegalArgumentException when the category is null, since a null equality filter is meaningless in the query layer.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessDefinitionQueryImpl.java:96

        super(commandExecutor);
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionId(String processDefinitionId) {
        this.id = processDefinitionId;
        return this;
    }

    @Override
    public ProcessDefinitionQuery processDefinitionIds(Set<String> processDefinitionIds) {
        this.ids = processDefinitionIds;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionCategory(String category) {
        if (category == null) {
            throw new ActivitiIllegalArgumentException("category is null");
        }
        this.category = category;
        return this;
    }

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

    @Override
    public ProcessDefinitionQueryImpl processDefinitionCategoryNotEquals(String categoryNotEquals) {
        if (categoryNotEquals == null) {
            throw new ActivitiIllegalArgumentException("categoryNotEquals is null");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null category string that matches deployed definitions.
2. Null-check the category before applying the filter; skip processDefinitionCategory() when filtering isn't needed.
3. Verify the deployed BPMN XML actually declares the expected category.
4. Catch ActivitiIllegalArgumentException around the query to return a user-friendly message.

Example fix

// before
query.processDefinitionCategory(attributes.get("category")); // may be null
// after
String category = attributes.get("category");
if (category != null) {
    query.processDefinitionCategory(category);
}

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

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

try {
    query.processDefinitionCategory(category);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    throw new BadRequestException("category filter must not be null", e);
}

When it happens

Trigger: Calling processDefinitionQuery.processDefinitionCategory(null), often when the category is read from a BPMN model attribute or config that is absent.

Common situations: Deployed BPMN XML lacking a category and code assuming it exists; passing a map lookup result (map.get("category")) straight into the query.

Related errors

• categoryLike is null
• categoryNotEquals is null
• name is null
• process definition id is null
• process definition id is null

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