flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process category list is null

Error message

Process category list is null

What it means

HistoricTaskInstanceQueryImpl.processCategoryIn() throws ActivitiIllegalArgumentException when the process category list is null. A null list is treated as a programming error rather than 'no filter'; pass an explicit list of category keys or omit the call. Categories correspond to process definition category values (e.g. from the BPMN targetNamespace mapping).

Solutions

1. Pass a concrete non-null list of category strings to processCategoryIn.
2. Only call processCategoryIn when the list is available: wrap in a null check.
3. Fix the producing code to return an empty list instead of null (though an empty list triggers its own error, so treat 'no filter' as skip-the-call).

Example fix

// before
query.processCategoryIn(categories); // categories may be null

// after
if (categories != null) {
    query.processCategoryIn(categories);
}

if (processCategoryInList == null || processCategoryInList.isEmpty()) { throw new IllegalArgumentException("processCategoryInList must be non-null and non-empty"); }

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

try {
    query.processCategoryIn(categories);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    log.warn("Skipping category filter: {}", e.getMessage());
}

When it happens

Trigger: Calling historicTaskInstanceQuery.processCategoryIn(null).

Common situations: Passing a variable that was never initialized; a lookup method returning null instead of an empty list; conditional query-building code that forwards a null unconditionally.

Related errors

• Process definition category is null
• Process definition id is null
• Process definition key is null
• Process definition name is null
• Process definition version is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/HistoricTaskInstanceQueryImpl.java:294

            this.processDefinitionName = processDefinitionName;
        }
        return this;
    }

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

    @Override
    public HistoricTaskInstanceQuery 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 (inOrStatement) {
            currentOrQueryObject.processCategoryInList = processCategoryInList;
        } else {
            this.processCategoryInList = processCategoryInList;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)