flowable/flowable-engine · error · FlowableIllegalArgumentException

Plan item definition id is null

Error message

Plan item definition id is null

What it means

Flowable's PlanItemInstanceQuery.planItemDefinitionId() throws FlowableIllegalArgumentException when planItemDefinitionId is null. This filter selects plan item instances by their definition id (the id of the plan item definition in the CMMN model); null is rejected eagerly at query-build time.

Solutions

1. Pass a valid plan item definition id from the CMMN model (e.g. via CmmnModel.getPlanItem(id).getPlanItemDefinition().getId())
2. Skip the filter when the id is null instead of passing null
3. Fix the model/key resolution so the definition id is resolved before query construction

Example fix

// before
query.planItemDefinitionId(definitionId); // throws when definitionId == null

// after
if (definitionId != null) {
    query.planItemDefinitionId(definitionId);
}

if (planItemDefinitionId != null && !planItemDefinitionId.isBlank()) {
    query.planItemDefinitionId(planItemDefinitionId);
}

boolean isPresent(String id) { return id != null && !id.isBlank(); }

try {
    query.planItemDefinitionId(planItemDefinitionId);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("planItemDefinitionId is required", e);
}

When it happens

Trigger: Calling planItemDefinitionId(null), usually when the definition id comes from an unresolved lookup (e.g. CmmnModel/PlanItemDefinition lookup by a wrong key), an empty configuration value, or a missing REST parameter.

Common situations: Report builders parameterized by plan item definition where the parameter is optional; model parsing code that fails to resolve the definition and returns null; version upgrades where definition ids/keys changed in the redesigned CMMN model.

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/47ef420c4331ce30. Report an issue: GitHub.

Appendix: source

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

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

View on GitHub (pinned to d6d39ce1c6)