flowable/flowable-engine · error · FlowableIllegalArgumentException

caseInstanceId is null

Error message

caseInstanceId is null

What it means

FlowableIllegalArgumentException thrown by GetCaseVariableInstanceCmd.execute when caseInstanceId is null. The command needs a case instance id to look up the variable instance for the given variable name. This is a leading argument-validation guard before any query runs.

Source

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

import org.flowable.common.engine.impl.interceptor.CommandContext;
import org.flowable.variable.api.persistence.entity.VariableInstance;

public class GetCaseVariableInstanceCmd implements Command<VariableInstance>, Serializable {

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

    public GetCaseVariableInstanceCmd(String caseInstanceId, String variableName) {
        this.caseInstanceId = caseInstanceId;
        this.variableName = variableName;
    }

    @Override
    public VariableInstance execute(CommandContext commandContext) {
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("caseInstanceId is null");
        }
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variableName is null");
        }

        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        CaseInstanceEntity caseInstance = cmmnEngineConfiguration.getCaseInstanceEntityManager().findById(caseInstanceId);

        if (caseInstance == null) {
            throw new FlowableObjectNotFoundException("case instance " + caseInstanceId + " doesn't exist", CaseInstance.class);
        }

        return caseInstance.getVariableInstance(variableName, false);
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a valid non-null caseInstanceId to getCaseVariableInstance
2. Validate the id in the caller before invoking the engine
3. Resolve the case instance id from the business key or execution context if it was never supplied

Example fix

// before
VariableInstance vi = caseService.getCaseVariableInstance(caseInstanceId, varName);
// after
if (caseInstanceId != null) {
    VariableInstance vi = caseService.getCaseVariableInstance(caseInstanceId, varName);
}

if (caseInstanceId == null || variableName == null) throw new IllegalArgumentException("caseInstanceId and variableName are required");

boolean hasCaseId = caseInstanceId instanceof String && !((String) caseInstanceId).isEmpty();

When it happens

Trigger: Calling caseService.getCaseVariableInstance(null, variableName) or variableInstance queries built through the service with an unset caseInstanceId.

Common situations: Variable passed from an unset request parameter or path variable; id lost when chaining calls across services; generic variable-lookup helper invoked before the case instance was created.

Related errors

• caseInstanceId is null
• variables is null
• Must specify a case instance id to migrate
• Must specify a case instance migration document to migrate
• Must specify a case definition id to migrate

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