flowable/flowable-engine · error · FlowableIllegalArgumentException

The case definition id must be provided when creating a new…

Error message

The case definition id must be provided when creating a new plan item instance

What it means

During PlanItemInstanceEntityBuilderImpl.validateData(), the caseDefinitionId field must be non-null; a plan item instance is always tied to a case definition, so create() throws this FlowableIllegalArgumentException when it is missing. Sibling checks cover planItem and caseInstanceId.

Solutions

Set caseDefinitionId on the builder before create().
Fetch the definition id from the case instance (caseInstance.getCaseDefinitionId()) and pass it in.
Add a null check/precondition in custom code that assembles the builder.

Example fix

// before
builder.planItem(planItem).caseInstanceId(caseInstanceId).create();
// after
builder.planItem(planItem)
    .caseDefinitionId(caseInstance.getCaseDefinitionId())
    .caseInstanceId(caseInstanceId).create();

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean ready = planItem != null && caseDefinitionId != null && caseInstanceId != null;

Try / catch

try { entity = builder.create(); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().contains("case definition id must be provided")) { /* set caseDefinitionId(...) */ } throw e; }

Prevention

Pass caseInstance.getCaseDefinitionId() when the definition id isn't at hand.
Enforce all three required fields in a helper that finalizes the builder.
Add builder preconditions to integration tests.
Never create plan item instances outside a valid case definition context.

When it happens

Trigger: Calling create() on a plan item instance builder without setting caseDefinitionId(...) (even if planItem and caseInstanceId are provided).

Common situations: Custom engine extensions or tests building plan item instances where only the case instance id was known; builder configuration taken from an incomplete snippet.

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

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

Appendix: source

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

    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)