flowable/flowable-engine · error · FlowableIllegalArgumentException

Plan item definition types is null

Error message

Plan item definition types is null

What it means

HistoricPlanItemInstanceQueryImpl.planItemInstanceDefinitionTypes() requires a non-null List of plan item definition types; null raises FlowableIllegalArgumentException because the filter cannot distinguish null from an intentional no-filter.

Source

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

    }

    @Override
    public HistoricPlanItemInstanceQuery planItemInstanceDefinitionType(String planItemDefinitionType) {
        if (planItemDefinitionType == null) {
            throw new FlowableIllegalArgumentException("Plan item definition type is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.planItemDefinitionType = planItemDefinitionType;
        } else {
            this.planItemDefinitionType = planItemDefinitionType;
        }
        return this;
    }

    @Override
    public HistoricPlanItemInstanceQuery planItemInstanceDefinitionTypes(List<String> planItemDefinitionTypes) {
        if (planItemDefinitionTypes == null) {
            throw new FlowableIllegalArgumentException("Plan item definition types is null");
        }
        if (planItemDefinitionTypes.isEmpty()) {
            throw new FlowableIllegalArgumentException("Plan item definition types is empty");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.planItemDefinitionTypes = planItemDefinitionTypes;
        } else {
            this.planItemDefinitionTypes = planItemDefinitionTypes;
        }
        return this;
    }

    @Override
    public HistoricPlanItemInstanceQuery planItemInstanceStartUserId(String startUserId) {
        if (inOrStatement) {
            this.currentOrQueryObject.startUserId = startUserId;
        } else {
            this.startUserId = startUserId;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Null-check the list before calling and skip the filter when null
2. Initialize to an empty List and only call the method when non-empty
3. Use planItemInstanceDefinitionType for a single type instead of a list
4. Fix the deserialization/upstream code so the list is populated

Example fix

// before
query.planItemInstanceDefinitionTypes(types).list();
// after
if (types != null && !types.isEmpty()) {
    query.planItemInstanceDefinitionTypes(types);
}
List<HistoricPlanItemInstance> results = query.list();

if (types != null && !types.isEmpty()) {
    query.planItemInstanceDefinitionTypes(types);
}

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

try {
    query.planItemInstanceDefinitionTypes(types);
} catch (FlowableIllegalArgumentException e) {
    if (!e.getMessage().contains("Plan item definition types is null")) throw e;
    // proceed without the types filter
}

When it happens

Trigger: Calling planItemInstanceDefinitionTypes(null), typically from an uninitialized collection variable or a deserialized payload missing the field.

Common situations: REST request bodies omitting the types array; Optional misuse producing null instead of a default list.

Related errors

• tenant id is null
• Set of case instance ids is null
• Plan item definition type is null
• EntryCriterionId is null
• Case instance id is null

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