flowable/flowable-engine · error · FlowableIllegalArgumentException

The plan item must be provided when creating a new plan…

Error message

The plan item must be provided when creating a new plan item instance

What it means

PlanItemInstanceEntityBuilderImpl.create() calls validateData() before creating a PlanItemInstanceEntity. The planItem field is mandatory — without it the engine cannot instantiate the plan item instance — so a null planItem yields this FlowableIllegalArgumentException.

Solutions

1. Set the plan item on the builder before create(): builder.planItem(planItem).
2. Ensure the PlanItem is resolved from the CaseDefinition's CmmnModel before building the instance.
3. Review custom code that builds plan item instances and add the missing planItem(...) call.

Example fix

// before
cmmnRuntimeService.createPlanItemInstanceBuilder()
    .caseDefinitionId(defId).caseInstanceId(instId).create();
// after
cmmnRuntimeService.createPlanItemInstanceBuilder()
    .planItem(planItem).caseDefinitionId(defId).caseInstanceId(instId).create();

if (planItem == null) throw new IllegalArgumentException("planItem is required before create()");

boolean canCreate = builder != null && planItem != null && caseDefinitionId != null && caseInstanceId != null;

try { entity = builder.create(); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().contains("plan item must be provided")) { /* set planItem(...) */ } throw e; }

When it happens

Trigger: Building a plan item instance via PlanItemInstanceEntityBuilderImpl (e.g. createPlanItemInstanceBuilder()) and calling create() without ever setting planItem(...).

Common situations: Custom engine extensions/tests constructing plan item instances programmatically; partial builder configuration copied from other builders; forgetting the builder call chain before create().

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• The case definition id must be provided when creating a new…
• A 'maxInstanceCount' on a repetition rule with value '0' is…
• A resource name is mandatory
• A script is required
• An assignee is required when delegating a task.

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/persistence/entity/PlanItemInstanceEntityBuilderImpl.java:136

    public String getTenantId() {
        return tenantId;
    }
    public Map<String, Object> getLocalVariables() {
        return localVariables;
    }
    public boolean hasLocalVariables() {
        return localVariables != null && localVariables.size() > 0;
    }
    public boolean isAddToParent() {
        return addToParent;
    }
    public boolean isSilentNameExpressionEvaluation() {
        return silentNameExpressionEvaluation;
    }

    protected void validateData() {
        if (planItem == null) {
            throw new FlowableIllegalArgumentException("The plan item must be provided when creating a new plan item instance");
        }
        if (caseDefinitionId == null) {
            throw new FlowableIllegalArgumentException("The case definition id must be provided when creating a new plan item instance");
        }
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("The case instance id must be provided when creating a new plan item instance");
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)