flowable/flowable-engine · error · FlowableIllegalArgumentException

Process category list is null

Error message

Process category list is null

What it means

HistoricTaskInstanceQueryImpl.processCategoryIn(Collection<String>) validates its input and throws FlowableIllegalArgumentException('Process category list is null') when the collection argument is null. The category IN predicate requires an actual list; the builder fails fast instead of producing broken SQL.

Solutions

1. Null-check before calling and skip the predicate when categories are absent.
2. Initialize the collection at declaration (new ArrayList<>()) so it is never null.
3. Normalize null at the data boundary to an empty list and branch on emptiness instead.

Example fix

// before
query.processCategoryIn(config.getCategories()); // null when unconfigured

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

if (categories == null) { categories = Collections.emptyList(); }

boolean isUsableCategoryList(Collection<String> c) { return c != null && !c.isEmpty(); }

try {
    query.processCategoryIn(categories);
} catch (FlowableIllegalArgumentException e) {
    // fall back to query without category filter
}

When it happens

Trigger: Calling historicTaskInstanceQuery().processCategoryIn(null), usually when the categories collection originates from an uninitialized field or an API that returns null for 'no categories'.

Common situations: Dynamic dashboards/filters where the selected categories list was never initialized; configuration lookup returning null when no category filter is configured.

Related errors

• Process instance id list is null
• appsDefinitionIds is null
• Business status is null
• callback type is null
• callbackIds is null or empty

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

Appendix: source

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

            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(Collection<String> processCategoryInList) {
        if (processCategoryInList == null) {
            throw new FlowableIllegalArgumentException("Process category list is null");
        }
        if (processCategoryInList.isEmpty()) {
            throw new FlowableIllegalArgumentException("Process category list is empty");
        }
        for (String processCategory : processCategoryInList) {
            if (processCategory == null) {
                throw new FlowableIllegalArgumentException("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)