flowable/flowable-engine · warning · FlowableIllegalArgumentException

planItemInstanceId is null

Error message

planItemInstanceId is null

What it means

Thrown as FlowableIllegalArgumentException by RemoveLocalVariableCmd when the planItemInstanceId supplied to remove a local variable from a plan item instance is null. The command validates its arguments before looking up the plan item instance.

Solutions

1. Fetch a valid plan item instance id via runtimeService.createPlanItemInstanceQuery() before removing the variable
2. Add a null/empty check on the caller side and fail fast with a clear message
3. Fix the upstream code that yields the null id

Example fix

// before
runtimeService.removeLocalVariable(planItemInstanceId, "score"); // id was null
// after
if (planItemInstanceId != null) {
    runtimeService.removeLocalVariable(planItemInstanceId, "score");
}

boolean canRemove = planItemInstanceId != null && variableName != null;

try { runtimeService.removeLocalVariable(planItemInstanceId, variableName); }
catch (FlowableIllegalArgumentException e) { /* null argument */ }

When it happens

Trigger: Calling CmmnRuntimeService.removeLocalVariable(null, variableName) (or the plan-item variant) with a null plan item instance id.

Common situations: A variable or lookup that should have produced the plan item instance id returned null; accidentally calling the plan-item overload with values swapped.

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

• planItemInstanceId is null
• variableName is null
• variableNames is null
• Case instance id is required
• executionId is null

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

Appendix: source

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

import org.flowable.common.engine.impl.interceptor.CommandContext;

/**
 * @author Tijs Rademakers
 */
public class RemoveLocalVariableCmd implements Command<Void> {
    
    protected String planItemInstanceId;
    protected String variableName;
    
    public RemoveLocalVariableCmd(String planItemInstanceId, String variableName) {
        this.planItemInstanceId = planItemInstanceId;
        this.variableName = variableName;
    }
    
    @Override
    public Void execute(CommandContext commandContext) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("planItemInstanceId is null");
        }
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variableName is null");
        }
     
        PlanItemInstanceEntity planItemInstanceEntity = CommandContextUtil.getPlanItemInstanceEntityManager(commandContext).findById(planItemInstanceId);
        if (planItemInstanceEntity == null) {
            throw new FlowableObjectNotFoundException("No plan item instance found for id " + planItemInstanceId, PlanItemInstanceEntity.class);
        }
        planItemInstanceEntity.removeVariable(variableName);
        
        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)