flowable/flowable-engine · error · FlowableIllegalArgumentException

category is null

Error message

category is null

What it means

ProcessDefinitionQueryImpl.processDefinitionCategory() filters process definitions by their exact category (the BPMN targetNamespace-derived category), which must be non-null. A null category cannot form a valid equality filter, so the query throws FlowableIllegalArgumentException eagerly. This is a fail-fast argument validation on the query builder.

Source

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

        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 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");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the category value at the entry point and reject the request before building the query.
2. Guard the call: if (category != null) query.processDefinitionCategory(category);
3. If category is an optional filter, omit the call rather than passing null.
4. Verify deployed BPMN resources actually carry the intended category/targetNamespace.

Example fix

// before
ProcessDefinitionQuery query = repositoryService.createProcessDefinitionQuery()
    .processDefinitionCategory(request.getCategory()); // may be null

// after
ProcessDefinitionQuery query = repositoryService.createProcessDefinitionQuery();
if (request.getCategory() != null) {
    query.processDefinitionCategory(request.getCategory());
}

if (category == null || category.isEmpty()) {
    return repositoryService.createProcessDefinitionQuery(); // no category filter
}
return repositoryService.createProcessDefinitionQuery().processDefinitionCategory(category);

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

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

When it happens

Trigger: Calling ProcessDefinitionQuery.processDefinitionCategory(null), usually when the category is read from an optional request parameter, deployment metadata, or a config value that was never set.

Common situations: REST search endpoints forwarding query params verbatim where 'category' was omitted; BPMN files deployed without a targetNamespace so the expected category never exists; copying category values between environments with different configuration.

Related errors

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

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