flowable/flowable-engine · error · FlowableIllegalArgumentException

planItemDefinitionIds is null

Error message

planItemDefinitionIds is null

What it means

HistoricCaseInstanceQueryImpl.activePlanItemDefinitionIds(Set<String>) throws FlowableIllegalArgumentException when the set of plan item definition ids is null. The set is stored directly on the query (or its OR object) to build an IN clause, so a null set is invalid input and is rejected eagerly.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java:1069

    }

    @Override
    public HistoricCaseInstanceQuery activePlanItemDefinitionId(String planItemDefinitionId) {
        if (planItemDefinitionId == null) {
            throw new FlowableIllegalArgumentException("planItemDefinitionId is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.activePlanItemDefinitionId = planItemDefinitionId;
        } else {
            this.activePlanItemDefinitionId = planItemDefinitionId;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQuery activePlanItemDefinitionIds(Set<String> planItemDefinitionIds) {
        if (planItemDefinitionIds == null) {
            throw new FlowableIllegalArgumentException("planItemDefinitionIds is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.activePlanItemDefinitionIds = planItemDefinitionIds;
        } else {
            this.activePlanItemDefinitionIds = planItemDefinitionIds;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQuery involvedUser(String userId) {
        if (userId == null) {
            throw new FlowableIllegalArgumentException("involvedUser is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.involvedUser = userId;
        } else {
            this.involvedUser = userId;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null Set; initialize with new HashSet<>() or Set.of() rather than leaving the variable null.
2. Only call activePlanItemDefinitionIds when the set is present; skip the filter otherwise.
3. Ensure list-to-set conversion helpers never return null (return an empty set instead).
4. Check that a mapping/config step didn't fail silently and leave the set unset.

Example fix

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

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

boolean isNonEmpty(Set<String> s) {
    return s != null && !s.isEmpty();
}

try {
    query.activePlanItemDefinitionIds(ids);
} catch (FlowableIllegalArgumentException e) {
    if ("planItemDefinitionIds is null".equals(e.getMessage())) {
        // treat as no filter or rethrow with context
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling activePlanItemDefinitionIds(null) on a HistoricCaseInstanceQuery, inside or outside an or() block, before executing the query.

Common situations: A downstream method returns null instead of an empty set when no plan item definitions match; deserialization of a config list yields null; constructing queries generically where the set parameter is optional but passed as null.

Related errors

• variableNames is null or empty
• planItemDefinitionId is null
• involvedUser is null
• userId is null
• identityLinkType is null

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