flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable value is missing for variable:

Error message

Variable value is missing for variable:

What it means

In HistoricTaskInstanceBaseResource.addProcessVariables, any operation other than EXISTS or NOT_EXISTS requires a non-null variable value. A null value with, e.g., EQUALS cannot be turned into a meaningful process-variable predicate, so FlowableIllegalArgumentException is thrown naming the variable.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/history/task/HistoricTaskInstanceBaseResource.java:421

            case NOT_EXISTS:
                taskInstanceQuery.taskVariableNotExists(variable.getName());
                break;

            default:
                throw new FlowableIllegalArgumentException("Unsupported variable query operation: " + variable.getVariableOperation());
            }
        }
    }

    protected void addProcessVariables(HistoricTaskInstanceQuery taskInstanceQuery, 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) {
                throw new FlowableIllegalArgumentException("Value-only query (without a variable-name) is not supported.");
            }

            switch (variable.getVariableOperation()) {

            case EQUALS:
                taskInstanceQuery.processVariableValueEquals(variable.getName(), actualValue);
                break;

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Provide the variable value for comparison operations.
  2. Use variableOperation EXISTS or NOT_EXISTS when you intend to test variable presence (these explicitly allow a null value).
  3. Validate value non-null for non-existence operations before sending the request.
  4. Catch FlowableIllegalArgumentException and report the offending variable name.

Example fix

// before
{"name": "amount", "variableOperation": "EQUALS", "value": null}
// after
{"name": "amount", "variableOperation": "EXISTS"}
Defensive patterns

Strategy: validation

Validate before calling

if (v.getVariableOperation() != EXISTS && v.getVariableOperation() != NOT_EXISTS && v.getValue() == null)
    throw new IllegalArgumentException("value required for operation " + v.getVariableOperation() + " on variable: " + v.getName());

Try / catch

try { return queryResponse(query); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().startsWith("Variable value is missing")) { /* switch to EXISTS or supply value */ } throw e; }

Prevention

When it happens

Trigger: GET /cmmn-history/historic-task-instances with a processVariable filter like {"name": "amount", "variableOperation": "EQUALS"} (no value), or value explicitly null, with an operation other than EXISTS/NOT_EXISTS.

Common situations: Trying to find tasks where a variable is unset by sending value:null with EQUALS; templated query builders leaving value blank; JSON bodies where null fields are preserved instead of dropped.

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/30fb35c37baca0d5. Report an issue: GitHub.