flowable/flowable-engine · warning · FlowableIllegalArgumentException

planItemInstanceId is null

Error message

planItemInstanceId is null

What it means

Thrown as FlowableIllegalArgumentException by RemoveLocalVariablesCmd when the planItemInstanceId is null. This bulk variant removes several local variables from one plan item instance and validates arguments before any lookup.

Solutions

1. Obtain a valid plan item instance id from planItemInstanceQuery before the bulk removal
2. Guard the call site against null ids
3. Fix the upstream producer of the id

Example fix

// before
runtimeService.removeLocalVariables(planItemInstanceId, names); // id null
// after
if (planItemInstanceId != null && names != null) {
    runtimeService.removeLocalVariables(planItemInstanceId, names);
}

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

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

When it happens

Trigger: Calling CmmnRuntimeService.removeLocalVariables(null, variableNames) with a null plan item instance id.

Common situations: Same as the single-variable variant: uninitialized id field, lookup returning null, wrong overload invoked.

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/aa3491f5c1f4c4b4. Report an issue: GitHub.

Appendix: source

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

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

/**
 * @author Tijs Rademakers
 */
public class RemoveLocalVariablesCmd implements Command<Void> {
    
    protected String planItemInstanceId;
    protected Collection<String> variableNames;
    
    public RemoveLocalVariablesCmd(String planItemInstanceId, Collection<String> variableNames) {
        this.planItemInstanceId = planItemInstanceId;
        this.variableNames = variableNames;
    }
    
    @Override
    public Void execute(CommandContext commandContext) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("planItemInstanceId is null");
        }
        if (variableNames == null) {
            throw new FlowableIllegalArgumentException("variableNames 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.removeVariables(variableNames);
        
        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)