flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process category list is null

Error message

Process category list is null

What it means

TaskQueryImpl.processCategoryIn(List<String>) throws ActivitiIllegalArgumentException when the processCategoryInList is null. Categories filter tasks by the category of their underlying process definition, and a null list cannot form the required IN clause, so it is rejected at query-build time.

Solutions

1. Default the category list to Collections.emptyList() at the source so it is never null.
2. Only call processCategoryIn when the list is non-null and non-empty.
3. Catch ActivitiIllegalArgumentException around query construction to surface a clear validation error.

Example fix

// before
List<String> categories = config.getCategories(); // may be null
taskQuery.processCategoryIn(categories);

// after
List<String> categories = config.getCategories();
if (categories != null && !categories.isEmpty()) {
    taskQuery.processCategoryIn(categories);
}

if (processCategoryInList == null || processCategoryInList.isEmpty()) {
    // skip category filter
} else {
    taskQuery.processCategoryIn(processCategoryInList);
}

boolean hasCategories(List<String> categories) { return categories != null && !categories.isEmpty(); }

try {
    return taskQuery.processCategoryIn(categories).list();
} catch (ActivitiIllegalArgumentException e) {
    log.warn("Invalid category filter: {}", e.getMessage());
    throw new BadRequestException(e.getMessage());
}

When it happens

Trigger: Calling taskQuery.processCategoryIn(null), typically when the category list comes from an unset config property, null request parameter, or failed lookup.

Common situations: Category-based task dashboards whose filter options are configured per environment; a missing or misnamed config key yields null and is passed straight into the query.

Related errors

• Candidate group list is empty
• Candidate group list is null
• None of the given process instance ids can be null
• Process category list is empty
• Process instance id list is empty

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/TaskQueryImpl.java:1032

            this.processDefinitionName = processDefinitionName;
        }
        return this;
    }

    @Override
    public TaskQuery processDefinitionNameLike(String processDefinitionNameLike) {
        if (orActive) {
            currentOrQueryObject.processDefinitionNameLike = processDefinitionNameLike;
        } else {
            this.processDefinitionNameLike = processDefinitionNameLike;
        }
        return this;
    }

    @Override
    public TaskQuery processCategoryIn(List<String> processCategoryInList) {
        if (processCategoryInList == null) {
            throw new ActivitiIllegalArgumentException("Process category list is null");
        }
        if (processCategoryInList.isEmpty()) {
            throw new ActivitiIllegalArgumentException("Process category list is empty");
        }
        for (String processCategory : processCategoryInList) {
            if (processCategory == null) {
                throw new ActivitiIllegalArgumentException("None of the given process categories can be null");
            }
        }

        if (orActive) {
            currentOrQueryObject.processCategoryInList = processCategoryInList;
        } else {
            this.processCategoryInList = processCategoryInList;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)