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

Null-check the type before calling and skip the filter when null

flowable/flowable-engine · error · FlowableIllegalArgumentException

Plan item definition type is null

Error message

Plan item definition type is null

What it means

HistoricPlanItemInstanceQueryImpl.planItemInstanceDefinitionType() rejects a null planItemDefinitionType with FlowableIllegalArgumentException. The definition type (e.g. 'humanTask', 'userEventListener') must be a concrete string for the filter.

Source

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

            this.elementId = elementId;
        }
        return this;
    }

    @Override
    public HistoricPlanItemInstanceQuery planItemInstanceDefinitionId(String planItemDefinitionId) {
        if (inOrStatement) {
            this.currentOrQueryObject.planItemDefinitionId = planItemDefinitionId;
        } else {
            this.planItemDefinitionId = planItemDefinitionId;
        }
        return this;
    }

    @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) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Null-check the type before calling and skip the filter when null
Pass a valid plan item definition type string (e.g. "humanTask")
Use planItemInstanceDefinitionTypes(List) when multiple types may apply and omit the filter if the list is empty
Fix the constant/config source that resolves to null

Example fix

// before
query.planItemInstanceDefinitionType(type).list();
// after
if (type != null) {
    query.planItemInstanceDefinitionType(type);
}
List<HistoricPlanItemInstance> results = query.list();

Defensive patterns

Strategy: validation

Validate before calling

if (planItemDefinitionType != null) {
    query.planItemInstanceDefinitionType(planItemDefinitionType);
}

Type guard

boolean hasType(String t) { return t != null && !t.isEmpty(); }

Try / catch

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

Prevention

Use named constants/enums for plan item definition types instead of raw strings from maps
Null-check config-driven or user-selected type values before filtering
Prefer the plural types() variant with a checked list when types are optional

When it happens

Trigger: Calling planItemInstanceDefinitionType(null), usually from a config value, enum lookup, or request parameter that is null.

Common situations: Mapping UI filter selections to CMMN plan item definition types where no selection maps to null; typos in constants resolved via reflection/maps.

Related errors

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