flowable/flowable-engine · error · FlowableIllegalArgumentException

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

Error message

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

What it means

Thrown by PlanItemInstanceEntityBuilderImpl.validateData when a plan item instance is created without a case instance id. The builder requires planItem, caseDefinitionId and caseInstanceId to all be set before constructing the entity. This is an internal invariant check protecting data integrity in the CMMN engine.

Solutions

1. Ensure caseInstanceId is set on the PlanItemInstanceEntityBuilder before create()
2. Verify the parent CaseInstanceEntity was started and persisted (has a generated id) before creating plan item instances
3. Check that any custom command that builds plan item instances passes the case instance id through

Example fix

// before
PlanItemInstanceEntityBuilderImpl builder = new PlanItemInstanceEntityBuilderImpl(commandContext)
    .planItem(planItem)
    .caseDefinitionId(caseDefinitionId);
// after
PlanItemInstanceEntityBuilderImpl builder = new PlanItemInstanceEntityBuilderImpl(commandContext)
    .planItem(planItem)
    .caseDefinitionId(caseDefinitionId)
    .caseInstanceId(caseInstance.getId());

if (planItem == null || caseDefinitionId == null || caseInstanceId == null) {
    throw new IllegalArgumentException("planItem, caseDefinitionId and caseInstanceId are all required");
}

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

try {
    builder.create();
} catch (FlowableIllegalArgumentException e) {
    // inspect builder state, re-run with caseInstanceId set
}

When it happens

Trigger: Calling the PlanItemInstanceEntityBuilder's create() with a builder where caseInstanceId was never set, even though planItem and caseDefinitionId were provided.

Common situations: Custom engine code or command extensions that construct plan item instances programmatically; engine upgrades where builder fields were added; copy/paste of builder code omitting one fluent setter call.

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

• Business status is null
• callback type is null
• callbackIds is null or empty
• Case definition keys is null
• caseInstance tenant id is null

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

Appendix: source

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

    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)