flowable/flowable-engine · warning · FlowableIllegalArgumentException

variableName is null

Error message

variableName is null

What it means

Thrown as FlowableIllegalArgumentException by RemoveLocalVariableCmd when the variableName to remove from the plan item instance is null. Both planItemInstanceId and variableName must be non-null for the command to proceed.

Solutions

1. Pass a concrete non-null variable name; check it before invoking
2. Verify the variable exists via planItemInstance/variable queries if removal should be conditional
3. Fix the source of the null name (config key, constant, lookup)

Example fix

// before
runtimeService.removeLocalVariable(instanceId, variableName); // variableName null
// after
if (variableName != null && !variableName.isEmpty()) {
    runtimeService.removeLocalVariable(instanceId, variableName);
}

boolean canRemove = variableName != null && !variableName.isEmpty();

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

When it happens

Trigger: Calling CmmnRuntimeService.removeLocalVariable(planItemInstanceId, null).

Common situations: Variable name kept in a config/field that was never set; string built dynamically and ended up null; copying the wrong variable from a template.

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
• planItemInstanceId is null
• variableNames is null
• executionId is null
• Invalid task id : null

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

Appendix: source

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

 * @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)