flowable/flowable-engine · error · FlowableIllegalArgumentException

The case definition id must be provided for the plan item…

Error message

The case definition id must be provided for the plan item instance

What it means

InjectedPlanItemInstanceBuilderImpl.validateData() is called before creating a dynamically injected plan item instance (createInStage/createInCase). The caseDefinitionId identifies which CMMN model the injected element belongs to; if null, validation fails with FlowableIllegalArgumentException.

Solutions

1. Call caseDefinitionId(...) with the deployed definition id before createInStage/createInCase
2. Resolve the id via caseInstance.getCaseDefinitionId() of the target case instance
3. Null-check the id lookup result before building

Example fix

// before
builder.elementId("task1").createInStage(stageId); // caseDefinitionId never set
// after
String defId = runtimeService.createCaseInstanceQuery()
    .caseInstanceId(caseInstanceId).singleResult().getCaseDefinitionId();
builder.caseDefinitionId(defId).elementId("task1").createInStage(stageId);

if (caseDefinitionId == null) { caseDefinitionId = caseInstance.getCaseDefinitionId(); }

boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }

try { builder.createInStage(stageId); } catch (FlowableIllegalArgumentException e) { log.error("Injection data invalid: {}", e.getMessage()); }

When it happens

Trigger: Calling createInjectedPlanItemInstanceBuilder(...) then createInStage/createInCase without calling caseDefinitionId(String), or with a null id (e.g., lookup returned nothing).

Common situations: Definition id obtained from a query that returned null; confusing caseInstanceId with caseDefinitionId; dynamically injecting plan items in a runtime-generated model where the id was never resolved.

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 element id must be provided for the plan item instance
• Could not resolve case instance id
• At least one correlation parameter value must be provided…
• Business status is null
• Can only trigger a plan item that is in the ACTIVE state

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

Appendix: source

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

    }

    @Override
    public PlanItemInstance createInStage(String stagePlanItemInstanceId) {
        validateData();
        this.stagePlanItemInstanceId = stagePlanItemInstanceId;
        return commandExecutor.execute(new CreateInjectedPlanItemInstanceCmd(this));
    }

    @Override
    public PlanItemInstance createInCase(String caseInstanceId) {
        validateData();
        this.caseInstanceId = caseInstanceId;
        return commandExecutor.execute(new CreateInjectedPlanItemInstanceCmd(this));
    }

    protected void validateData() {
        if (caseDefinitionId == null) {
            throw new FlowableIllegalArgumentException("The case definition id must be provided for the plan item instance");
        }
        if (elementId == null) {
            throw new FlowableIllegalArgumentException("The element id must be provided for the plan item instance");
        }
    }

    public boolean injectInStage() {
        return stagePlanItemInstanceId != null;
    }
    public boolean injectInCase() {
        return caseInstanceId != null;
    }
    public String getStagePlanItemInstanceId() {
        return stagePlanItemInstanceId;
    }
    public String getCaseInstanceId() {
        return caseInstanceId;
    }

View on GitHub (pinned to d6d39ce1c6)