flowable/flowable-engine · error · FlowableIllegalArgumentException

planItemInstanceId is null

Error message

planItemInstanceId is null

What it means

GetPlanItemVariableInstancesCmd throws FlowableIllegalArgumentException('planItemInstanceId is null') as its first validation step in execute(). It fetches all local VariableInstance objects for the plan item, but refuses to run when the id argument is missing. No entity lookup occurs in this case.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/GetPlanItemVariableInstancesCmd.java:42

import org.flowable.common.engine.impl.interceptor.CommandContext;
import org.flowable.variable.api.persistence.entity.VariableInstance;

public class GetPlanItemVariableInstancesCmd implements Command<Map<String, VariableInstance>>, Serializable {

    private static final long serialVersionUID = 1L;
    
    protected String planItemInstanceId;

    public GetPlanItemVariableInstancesCmd(String planItemInstanceId) {
        this.planItemInstanceId = planItemInstanceId;
    }

    @Override
    public Map<String, VariableInstance> execute(CommandContext commandContext) {

        // Verify existence of execution
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("planItemInstanceId is null");
        }

        PlanItemInstanceEntity planItemInstance = CommandContextUtil.getPlanItemInstanceEntityManager(commandContext).findById(planItemInstanceId);

        if (planItemInstance == null) {
            throw new FlowableObjectNotFoundException("plan item instance " + planItemInstanceId + " doesn't exist", PlanItemInstance.class);
        }

        return planItemInstance.getVariableInstancesLocal();
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Guarantee a non-null, resolved plan item id before invoking the API.
2. Add Objects.requireNonNull checks in wrapper code.
3. Filter out items lacking ids before batch variable retrieval.
4. Investigate the upstream resolution path that yielded null.

Example fix

// before
Map<String, VariableInstance> vars = cmmnRuntimeService.getPlanItemVariableInstances(planItemId);
// after
Objects.requireNonNull(planItemId, "planItemInstanceId must be set");
Map<String, VariableInstance> vars = cmmnRuntimeService.getPlanItemVariableInstances(planItemId);

Objects.requireNonNull(planItemInstanceId, "planItemInstanceId is required");

boolean hasPlanItemId(String id) { return id != null && !id.trim().isEmpty(); }

try {
    vars = cmmnRuntimeService.getPlanItemVariableInstances(planItemInstanceId);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Missing plan item id for variable read");
    vars = Collections.emptyMap();
}

When it happens

Trigger: Calling getPlanItemVariableInstances(planItemInstanceId) with a null id — usually because the id variable was never assigned, an upstream resolver failed, or a request body lacked the id field.

Common situations: Optional id fields in DTOs left unset; loops over plan items where some resolutions fail; script/expression contexts producing null; misuse of the API with case ids.

Related errors

• planItemInstanceId is null
• planItemInstanceId is null
• variableName is null
• caseInstanceId is null
• caseInstanceId is null

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