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

FlowableIllegalArgumentException thrown when a historic task query variable requires a value but has none. Operations other than EXISTS/NOT_EXISTS are value-based, so variable.getValue() == null makes the query condition meaningless and the request is rejected as invalid (HTTP 400).

Source

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

     * Throws the right exceptions when bad request was made or instance was not found.
     */
    protected HistoricTaskInstance getHistoricTaskInstanceFromRequestWithoutAccessCheck(String taskId) {
        HistoricTaskInstance taskInstance = historyService.createHistoricTaskInstanceQuery().taskId(taskId).singleResult();
        if (taskInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a task instance with id '" + taskId + "'.", HistoricTaskInstance.class);
        }
        
        return taskInstance;
    }

    protected void addTaskVariables(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.taskVariableValueEquals(variable.getName(), actualValue);
                break;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Provide a non-null "value" for the variable, e.g. {"name":"owner","operation":"EQUALS","value":"kermit"}.
2. If you intend to test variable presence, use operation EXISTS or NOT_EXISTS, which do not require a value.
3. Validate each variable (operation != EXISTS/NOT_EXISTS implies value != null) before sending the request.
4. For null-value semantics, restructure the query (e.g. filter by variable existence) since equality on null is not supported here.

Example fix

// before
{"name":"owner","operation":"EQUALS"}
// after
{"name":"owner","operation":"EQUALS","value":"kermit"}

function validateQueryVars(vars) {
  for (const v of vars.taskVariableValues || []) {
    const op = v.operation;
    if (op !== "EXISTS" && op !== "NOT_EXISTS" && (v.value === undefined || v.value === null)) {
      throw new Error("variable '" + v.name + "' with operation " + op + " requires a value");
    }
  }
}

const needsValue = (v) => v.operation !== "EXISTS" && v.operation !== "NOT_EXISTS";

When it happens

Trigger: POST /cmmn-history/historic-task-instances/query with a variable such as {"name":"owner","operation":"EQUALS"} and no value, or explicit "value":null for any non-EXISTS/NOT_EXISTS operation.

Common situations: Client code leaving the value field unset; trying to query for null values with EQUALS instead of using EXISTS/NOT_EXISTS semantics; template-generated requests with empty value placeholders.

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

• Variable operation is missing for variable: ${variable.getNa
• Value-only query (without a variable-name) is not supported.
• Variable operation is missing for variable:
• Variable value is missing for variable:
• Variable value is missing for variable: {variableName}

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