flowable/flowable-engine · error · FlowableIllegalArgumentException

caseInstanceId is null

Error message

caseInstanceId is null

What it means

SetVariablesCmd.execute performs mandatory-argument checks before touching the engine. The caseInstanceId is the primary key of the case instance whose variables will be replaced, so a null value is rejected immediately with FlowableIllegalArgumentException.

Source

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

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Ensure a non-null caseInstanceId is passed to setVariables.
  2. Check the code path producing the id; resolve it from a CaseInstance object or query before the call.
  3. Fail fast in caller code with a clear message when the id is null instead of reaching the engine.

Example fix

// before
runtimeService.setVariables(caseInstanceId, variables); // caseInstanceId may be null
// after
Objects.requireNonNull(caseInstanceId, "caseInstanceId must be set");
runtimeService.setVariables(caseInstanceId, variables);
Defensive patterns

Strategy: validation

Validate before calling

if (caseInstanceId == null || caseInstanceId.trim().isEmpty()) {
    throw new IllegalArgumentException("caseInstanceId must be provided");
}

Try / catch

try {
    runtimeService.setVariables(caseInstanceId, vars);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("caseInstanceId is null")) {
        // fix caller data path
    }
}

Prevention

When it happens

Trigger: Calling CmmnRuntimeService.setVariables(null, variables), or building a command where caseInstanceId was never assigned (e.g., missing builder field, unbound variable).

Common situations: Passing the result of a lookup that returned null straight into setVariables; copying code from a task-variable call and forgetting to set the case id; deserialization produced a null field.

Related errors

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