flowable/flowable-engine · error · FlowableIllegalArgumentException

The element id must be provided for the plan item instance

Error message

The element id must be provided for the plan item instance

What it means

InjectedPlanItemInstanceBuilderImpl.validateData() requires an elementId identifying the plan item (CMMN element) to inject. A null elementId means the engine cannot locate the model element, so FlowableIllegalArgumentException is thrown before createInStage/createInCase proceeds.

Solutions

1. Call elementId("<element id from CMMN XML>") before createInStage/createInCase
2. Verify the element id exists in the deployed case definition's model
3. Null-check configuration/lookup that supplies the element id

Example fix

// before
builder.caseDefinitionId(defId).createInCase(caseInstanceId); // elementId missing
// after
builder.caseDefinitionId(defId)
    .elementId("humanTask1")
    .createInCase(caseInstanceId);

if (elementId == null || elementId.isEmpty()) throw new IllegalArgumentException("elementId required");

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

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

When it happens

Trigger: Building the injected plan item instance builder without calling elementId(String), or passing null because the element id came from an unfound lookup/config.

Common situations: Wrong element id key in configuration; referencing an element id that does not exist in the CMMN diagram; copy-pasted builder code omitting elementId.

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 for the plan item…
• 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/9077dac87935d76a. Report an issue: GitHub.

Appendix: source

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

    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;
    }
    public String getName() {
        return name;
    }

View on GitHub (pinned to d6d39ce1c6)