flowable/flowable-engine · error · FlowableIllegalArgumentException

variableName is null

Error message

variableName is null

What it means

GetPlanItemVariableInstanceCmd also validates variableName and throws FlowableIllegalArgumentException when it is null. The plan item id check passes but the required variable name is missing, so the command aborts before loading the plan item. Variable names are mandatory keys into the instance's local variable scope.

Source

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

public class GetPlanItemVariableInstanceCmd implements Command<VariableInstance>, Serializable {

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

    public GetPlanItemVariableInstanceCmd(String planItemInstanceId, String variableName) {
        this.planItemInstanceId = planItemInstanceId;
        this.variableName = variableName;
    }

    @Override
    public VariableInstance execute(CommandContext commandContext) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("planItemInstanceId is null");
        }
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variableName 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.getVariableInstance(variableName, false);
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a concrete non-null variable name string.
2. Validate/trim configured variable names at load time and fail early with the config key in the message.
3. If the name is dynamic, guard against null evaluation results before the call.
4. For optional variables, use the all-variables API and check map membership instead.

Example fix

// before
VariableInstance vi = cmmnRuntimeService.getPlanItemVariableInstance(planItemId, varName); // varName may be null
// after
if (varName == null || varName.isEmpty()) { return null; }
VariableInstance vi = cmmnRuntimeService.getPlanItemVariableInstance(planItemId, varName);

Objects.requireNonNull(variableName, "variableName is required");
if (variableName.trim().isEmpty()) throw new IllegalArgumentException("variableName must not be blank");

boolean hasVariableName(String name) { return name != null && !name.trim().isEmpty(); }

try {
    vi = cmmnRuntimeService.getPlanItemVariableInstance(planItemInstanceId, variableName);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Missing variable name for plan item {}", planItemInstanceId);
    vi = null;
}

When it happens

Trigger: Calling getPlanItemVariableInstance(planItemInstanceId, variableName) with a null name — commonly from dynamic variable name expressions evaluating to null, or config-driven lookups with missing keys.

Common situations: Expression/EL evaluation returning null for the variable name; YAML/JSON config entries where the variable key was omitted; reflection-based generic variable access passing null for optional names.

Related errors

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

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