flowable/flowable-engine · error · FlowableIllegalArgumentException

variableName is null

Error message

variableName is null

What it means

RuntimeServiceImpl.setVariable(String executionId, String variableName, Object value) validates that variableName is non-null before dispatching SetExecutionVariablesCmd. Flowable throws FlowableIllegalArgumentException because a process variable cannot exist without a name; the null name would fail deep inside variable persistence with a less clear error.

Solutions

1. Ensure variableName is non-null before calling setVariable
2. Validate external/config-sourced variable names early (at parse time)
3. Fix the source of the null name (missing map entry, unset constant, malformed payload)
4. Catch FlowableIllegalArgumentException at the API boundary and return a validation error to the caller

Example fix

// before
runtimeService.setVariable(executionId, name, value); // name may be null
// after
Objects.requireNonNull(name, "variableName must not be null");
runtimeService.setVariable(executionId, name, value);

if (variableName == null) {
    throw new IllegalArgumentException("variableName must not be null before setVariable");
}

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

try {
    runtimeService.setVariable(executionId, name, value);
} catch (FlowableIllegalArgumentException e) {
    log.error("Rejected variable set: {}", e.getMessage());
    throw new ValidationException("Variable name is required");
}

When it happens

Trigger: Calling runtimeService.setVariable(executionId, null, value), typically when the variable name comes from config, a map iteration that yields null keys, or external input with missing 'name' fields.

Common situations: Deserializing variable definitions from JSON where the name field is absent; dynamic variable setting driven by user input; refactor renamed the variable constant and a reference became null.

Related errors

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

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/RuntimeServiceImpl.java:359

    @Override
    public VariableInstance getVariableInstanceLocal(String executionId, String variableName) {
        return commandExecutor.execute(new GetExecutionVariableInstanceCmd(executionId, variableName, true));
    }

    @Override
    public <T> T getVariableLocal(String executionId, String variableName, Class<T> variableClass) {
        return variableClass.cast(getVariableLocal(executionId, variableName));
    }

    @Override
    public boolean hasVariableLocal(String executionId, String variableName) {
        return commandExecutor.execute(new HasExecutionVariableCmd(executionId, variableName, true));
    }

    @Override
    public void setVariable(String executionId, String variableName, Object value) {
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variableName is null");
        }
        Map<String, Object> variables = new HashMap<>();
        variables.put(variableName, value);
        commandExecutor.execute(new SetExecutionVariablesCmd(executionId, variables, false));
    }

    @Override
    public void setVariableLocal(String executionId, String variableName, Object value) {
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variableName is null");
        }
        Map<String, Object> variables = new HashMap<>();
        variables.put(variableName, value);
        commandExecutor.execute(new SetExecutionVariablesCmd(executionId, variables, true));
    }

    @Override
    public void setVariables(String executionId, Map<String, ?> variables) {

View on GitHub (pinned to d6d39ce1c6)