flowable/flowable-engine · error · FlowableIllegalArgumentException

Plan Item instance id is null

Error message

Plan Item instance id is null

What it means

Flowable's PlanItemInstanceQuery.planItemInstanceId() throws FlowableIllegalArgumentException when planItemInstanceId is null. This filter targets a single plan item instance by its runtime id; null is rejected immediately in the setter. To query plan items by definition or element instead, use the corresponding filter methods.

Solutions

1. Pass the actual plan item instance id (e.g. planItemInstance.getId() from a trigger/complete callback)
2. Guard: only apply the filter when the id is non-null
3. Verify variable/payload keys — a typo in the variable name silently yields null

Example fix

// before
planItemInstanceQuery.planItemInstanceId((String) execution.getVariable("planItemId"));

// after
String planItemId = (String) execution.getVariable("planItemId");
if (planItemId != null) {
    planItemInstanceQuery.planItemInstanceId(planItemId);
}

String planItemId = (String) execution.getVariable("planItemId");
if (planItemId != null) {
    query.planItemInstanceId(planItemId);
}

String asString(Object v) { return v instanceof String s && !s.isBlank() ? s : null; }

try {
    query.planItemInstanceId(planItemId);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("planItemInstanceId is required", e);
}

When it happens

Trigger: Calling planItemInstanceId(null) — typically when a variable, message payload, or REST parameter holding the plan item instance id was never set, or when completing/triggering code passes a null id into a helper that builds the query.

Common situations: Custom event/job handlers reading ids from variables that weren't set; REST endpoints with missing path segments; copying listener code where the passed variable name changed between Flowable versions.

Related errors

• activatedBefore is null
• assignee is null
• availableAfter is null
• availableBefore is null
• before time is null

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

Appendix: source

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

    }

    @Override
    public PlanItemInstanceQuery stageInstanceId(String stageInstanceId) {
        if (stageInstanceId == null) {
            throw new FlowableIllegalArgumentException("Stage instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.stageInstanceId = stageInstanceId;
        } else {
            this.stageInstanceId = stageInstanceId;
        }
        return this;
    }
    
    @Override
    public PlanItemInstanceQuery planItemInstanceId(String planItemInstanceId) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("Plan Item instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.planItemInstanceId = planItemInstanceId;
        } else {
            this.planItemInstanceId = planItemInstanceId;
        }
        return this;
    }
    
    @Override
    public PlanItemInstanceQuery planItemInstanceElementId(String elementId) {
        if (elementId == null) {
            throw new FlowableIllegalArgumentException("Element id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.elementId = elementId;
        } else {
            this.elementId = elementId;

View on GitHub (pinned to d6d39ce1c6)