What causes "Task category list is null" in flowable/flowable-engine?

Null-check the collection before calling taskCategoryIn/taskCategoryNotIn

flowable/flowable-engine · error · FlowableIllegalArgumentException

Task category list is null

Error message

Task category list is null

What it means

The internal helper checkTaskCategoryList throws this when taskCategoryIn(...) / taskCategoryNotIn(...) is called with a null collection. The category filter requires an actual, non-empty list of category strings.

Solutions

Null-check the collection before calling taskCategoryIn/taskCategoryNotIn
Initialize the collection to an empty list and skip the filter when empty
Fix the upstream source that produces a null list

Example fix

// before
query.taskCategoryIn(categories); // may be null
// after
if (categories != null && !categories.isEmpty()) { query.taskCategoryIn(categories); }

Defensive patterns

Strategy: validation

Validate before calling

if (categories != null && !categories.isEmpty()) { query.taskCategoryIn(categories); }

Type guard

boolean isValidCategoryList(Collection<String> list) {
    return list != null && !list.isEmpty() && list.stream().allMatch(Objects::nonNull);
}

Try / catch

try {
    query.taskCategoryIn(categories);
} catch (FlowableIllegalArgumentException e) {
    // apply default or no category filter
}

Prevention

Never forward nullable collections into taskCategoryIn/taskCategoryNotIn
Default empty/null category inputs to 'no filter' semantics
Validate request DTOs before constructing queries

When it happens

Trigger: Calling taskCategoryIn(null) or taskCategoryNotIn(null), e.g. when a nullable variable or optional request parameter is passed straight through.

Common situations: REST endpoints mapping an absent query parameter to null; building filters from a map lookup that returns null for an unknown key.

Related errors

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

Appendix: source

Thrown at modules/flowable-task-service/src/main/java/org/flowable/task/service/impl/HistoricTaskInstanceQueryImpl.java:1841

            this.categoryInList = taskCategoryInList;
        }
        return this;
    }

    @Override
    public HistoricTaskInstanceQuery taskCategoryNotIn(Collection<String> taskCategoryNotInList) {
        checkTaskCategoryList(taskCategoryNotInList);
        if (inOrStatement) {
            currentOrQueryObject.categoryNotInList = taskCategoryNotInList;
        } else {
            this.categoryNotInList = taskCategoryNotInList;
        }
        return this;
    }

    protected void checkTaskCategoryList(Collection<String> taskCategoryInList) {
        if (taskCategoryInList == null) {
            throw new FlowableIllegalArgumentException("Task category list is null");
        }
        if (taskCategoryInList.isEmpty()) {
            throw new FlowableIllegalArgumentException("Task category list is empty");
        }
        for (String processCategory : taskCategoryInList) {
            if (processCategory == null) {
                throw new FlowableIllegalArgumentException("None of the given task categories can be null");
            }
        }
    }

    @Override
    public HistoricTaskInstanceQuery taskWithoutCategory() {
        if (inOrStatement) {
            currentOrQueryObject.withoutCategory = true;
        } else {
            this.withoutCategory = true;
        }

View on GitHub (pinned to d6d39ce1c6)