What causes "variables is null" in flowable/flowable-engine?

Pass an empty map (Collections.emptyMap()) if there is nothing to set, or skip the call entirely when the map is null.

flowable/flowable-engine · error · FlowableIllegalArgumentException

variables is null

Error message

variables is null

What it means

SetVariablesCmd requires a non-null variables map because it will call caseInstanceEntity.setVariables(variables). A null map cannot be processed, so execute throws FlowableIllegalArgumentException immediately after the caseInstanceId check.

Source

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

 * @author Joram Barrez
 */
public class SetVariablesCmd implements Command<Void> {
    
    protected String caseInstanceId;
    protected Map<String, Object> variables;
    
    public SetVariablesCmd(String caseInstanceId, Map<String, Object> variables) {
        this.caseInstanceId = caseInstanceId;
        this.variables = variables;
    }
    
    @Override
    public Void execute(CommandContext commandContext) {
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("caseInstanceId is null");
        }
        if (variables == null) {
            throw new FlowableIllegalArgumentException("variables is null");
        }
        if (variables.isEmpty()) {
            throw new FlowableIllegalArgumentException("variables is empty");
        }
     
        CaseInstanceEntity caseInstanceEntity = CommandContextUtil.getCaseInstanceEntityManager(commandContext).findById(caseInstanceId);
        if (caseInstanceEntity == null) {
            throw new FlowableObjectNotFoundException("No case instance found for id " + caseInstanceId, CaseInstanceEntity.class);
        }
        caseInstanceEntity.setVariables(variables);
        
        Set<String> variableNames = variables.keySet();
        
        CmmnEngineAgenda agenda = CommandContextUtil.getAgenda(commandContext);
        
        CmmnDeploymentManager deploymentManager = CommandContextUtil.getCmmnEngineConfiguration(commandContext).getDeploymentManager();
        CaseDefinition caseDefinition = deploymentManager.findDeployedCaseDefinitionById(caseInstanceEntity.getCaseDefinitionId());
        boolean evaluateVariableEventListener = false;

View on GitHub (pinned to d6d39ce1c6)

Solutions

Pass an empty map (Collections.emptyMap()) if there is nothing to set, or skip the call entirely when the map is null.
Instantiate the variables map (new HashMap<>()) before the call in all code paths.
Assert/map non-null at the caller boundary with a descriptive exception.

Example fix

// before
Map<String, Object> vars = null;
runtimeService.setVariables(caseInstanceId, vars);
// after
Map<String, Object> vars = new HashMap<>();
vars.put("status", "new");
runtimeService.setVariables(caseInstanceId, vars);

Defensive patterns

Strategy: validation

Validate before calling

if (variables == null) variables = Collections.emptyMap();
if (variables.isEmpty()) return; // nothing to set

Try / catch

try {
    runtimeService.setVariables(caseInstanceId, vars);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("variables is null")) {
        // re-initialize map or skip
    }
}

Prevention

Initialize maps at declaration, never leave them null
Skip no-op calls instead of passing null/empty collections
Cover variable-setting paths with unit tests

When it happens

Trigger: Calling CmmnRuntimeService.setVariables(caseInstanceId, null); a method that conditionally builds the map but skips creation on some branch and passes null.

Common situations: Initializing a map field to null and forgetting to instantiate it; refactoring that removed map construction; passing an expression result that evaluated to null.

Related errors

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