flowable/flowable-engine · error · FlowableIllegalArgumentException

Plan item definition type is null

Error message

Plan item definition type is null

What it means

This FlowableIllegalArgumentException is thrown by PlanItemInstanceQueryImpl.planItemDefinitionType when a null plan item definition type is passed. The CMMN engine query API rejects null filter values eagerly at query-construction time rather than producing an ambiguous SQL query later. It is a programmer-error guard: the filter must be a concrete string such as 'humanTask' or 'task'.

Solutions

1. Pass a concrete plan item definition type string (e.g. "task", "humanTask", "stage", "milestone", "eventListener").
2. Guard the call: only invoke planItemDefinitionType when the value is non-null; otherwise skip the filter.
3. If the intent was a multi-value filter, use planItemDefinitionTypes(List<String>) with a non-empty list.

Example fix

// before
query.planItemDefinitionType(request.getType()); // type may be null
// after
if (request.getType() != null) {
    query.planItemDefinitionType(request.getType());
}

if (type == null || type.isBlank()) {
    throw new IllegalArgumentException("planItemDefinitionType must be a non-null, non-empty string");
}
planItemInstanceQuery.planItemDefinitionType(type);

boolean isValidDefinitionType(String s) {
    return s != null && !s.isBlank();
}

try {
    query.planItemDefinitionType(type);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("Plan item definition type is null")) {
        // skip filter or surface a 400 to the caller
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling planItemInstanceQuery.planItemDefinitionType(null), or passing a variable/field that resolves to null into it while building a PlanItemInstanceQuery.

Common situations: Developers building dynamic query criteria from optional request parameters (e.g. a REST query param that is absent) and passing the unboxed null straight into the query builder.

Related errors

• activatedBefore is null
• assignee is null
• availableAfter is null
• availableBefore is null
• before time is null

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

Appendix: source

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

    }
    
    @Override
    public PlanItemInstanceQuery planItemDefinitionId(String planItemDefinitionId) {
        if (planItemDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Plan item definition id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.planItemDefinitionId = planItemDefinitionId;
        } else {
            this.planItemDefinitionId = planItemDefinitionId;
        }
        return this;
    }
    
    @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) {

View on GitHub (pinned to d6d39ce1c6)