What causes "Plan item definition types is null" in flowable/flowable-engine?

Pass a non-null list of definition types, e.g. Arrays.asList("task", "stage").

flowable/flowable-engine · error · FlowableIllegalArgumentException

Plan item definition types is null

Error message

Plan item definition types is null

What it means

Thrown by PlanItemInstanceQueryImpl.planItemDefinitionTypes when the list of plan item definition types is null. The query API requires a non-null, non-empty list to build an IN-style filter. Passing null would make the query criteria ambiguous, so the engine fails fast at builder time.

Solutions

Pass a non-null list of definition types, e.g. Arrays.asList("task", "stage").
Skip the call when the list is null (treat as 'no filter').
Return an empty list (not null) from list-producing helpers, then rely on the empty-check path or skip entirely.

Example fix

// before
query.planItemDefinitionTypes(filter.getTypes()); // may be null
// after
List<String> types = filter.getTypes();
if (types != null && !types.isEmpty()) {
    query.planItemDefinitionTypes(types);
}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
    query.planItemDefinitionTypes(types);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("Plan item definition types is null")) {
        // treat as unfiltered query or reject the request
    } else {
        throw e;
    }
}

Prevention

Return empty lists (never null) from list-producing helpers
Validate multi-select filters at the API boundary before building queries
Use Objects.requireNonNull with a clear message when the list is mandatory

When it happens

Trigger: Calling planItemInstanceQuery.planItemDefinitionTypes(null), typically with a list assembled from nullable upstream data (config, request params, a map lookup).

Common situations: A REST/GraphQL filter field for types is omitted and the collected list is null; or a helper method returns null instead of an empty list when no types are selected.

Related errors

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java:245

    }
    
    @Override
    public PlanItemInstanceQuery planItemDefinitionType(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 PlanItemInstanceQuery planItemDefinitionTypes(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 PlanItemInstanceQuery planItemInstanceName(String name) {
        if (name == null) {
            throw new FlowableIllegalArgumentException("Name is null");
        }
        if (inOrStatement) {

View on GitHub (pinned to d6d39ce1c6)