flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable value is missing for variable: ${variable.getName()

Error message

Variable value is missing for variable: ${variable.getName()}

What it means

Guard in HistoricCaseInstanceBaseResource.addVariables: a query variable was supplied whose name is set but whose value is missing/null, so the variable comparison for the historic case instance query cannot be built.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/history/caze/HistoricCaseInstanceBaseResource.java:315

    }

    protected HistoricCaseInstance getHistoricCaseInstanceFromRequestWithoutAccessCheck(String caseInstanceId) {
        HistoricCaseInstance caseInstance = historyService.createHistoricCaseInstanceQuery().caseInstanceId(caseInstanceId).singleResult();
        if (caseInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a case instance with id '" + caseInstanceId + "'.", HistoricCaseInstance.class);
        }

        return caseInstance;
    }

    protected void addVariables(HistoricCaseInstanceQuery caseInstanceQuery, List<QueryVariable> variables) {
        for (QueryVariable variable : variables) {
            if (variable.getVariableOperation() == null) {
                throw new FlowableIllegalArgumentException("Variable operation is missing for variable: " + variable.getName());
            }
            if (variable.getVariableOperation() != QueryVariableOperation.EXISTS && variable.getVariableOperation() != QueryVariableOperation.NOT_EXISTS) {
                if (variable.getValue() == null) {
                    throw new FlowableIllegalArgumentException("Variable value is missing for variable: " + variable.getName());
                }
            }

            boolean nameLess = variable.getName() == null;

            Object actualValue = restResponseFactory.getVariableValue(variable);

            // A value-only query is only possible using equals-operator
            if (nameLess && variable.getVariableOperation() != QueryVariableOperation.EQUALS) {
                throw new FlowableIllegalArgumentException("Value-only query (without a variable-name) is only supported when using 'equals' operation.");
            }

            switch (variable.getVariableOperation()) {

            case EQUALS:
                if (nameLess) {
                    caseInstanceQuery.variableValueEquals(actualValue);
                } else {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Provide a value for every variable that is not EXISTS/NOT_EXISTS
  2. Switch to operation "exists" if you only need to test variable presence
  3. Validate the payload before posting (name+operation+value triplet)
  4. Send a typed default value if the business case allows it

Example fix

// before
{"name":"amount","operation":"greaterThan"}
// after
{"name":"amount","operation":"greaterThan","value":100}
Defensive patterns

Strategy: validation

Validate before calling

if (!"exists".equals(op) && !"notExists".equals(op) && value == null)
  throw new IllegalArgumentException("Variable " + name + " requires a value");

Type guard

boolean valuePresent(Map<String,Object> v) {
  String op = (String) v.get("operation");
  return "exists".equals(op) || "notExists".equals(op) || v.get("value") != null;
}

Try / catch

try { ... } catch (FlowableIllegalArgumentException e) {
  return badRequest(e.getMessage());
}

Prevention

When it happens

Trigger: POST query payload with {"name":"x","operation":"equals"} and no "value" key (or explicit null).

Common situations: Templates with placeholder value left empty; client serializes null and omits value; developer assumed EXISTS-like semantics for equals.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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