What causes "Variable value is missing for variable: {variableName}" in flowable/flowable-engine?

Set the variable 'value' field in the query body to a concrete value

flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable value is missing for variable: {variableName}

Error message

Variable value is missing for variable: {variableName}

What it means

Flowable's REST task query endpoint validates each variable filter in the request body. If a variable declares an operation that requires a value (anything other than EXISTS/NOT_EXISTS) but the 'value' field is null, TaskBaseResource.addTaskvariables throws this FlowableIllegalArgumentException. The library refuses to build a TaskQuery with a valueless comparison.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/task/TaskBaseResource.java:392

            taskQuery.taskParentScopeId(request.getParentScopeId());
        }

        if (restApiInterceptor != null) {
            restApiInterceptor.accessTaskInfoWithQuery(taskQuery, request);
        }

        return paginateList(requestParams, request, taskQuery, "id", properties, restResponseFactory::createTaskResponseList);
    }

    protected void addTaskvariables(TaskQuery taskQuery, 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) {
                    taskQuery.taskVariableValueEquals(actualValue);
                } else {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Set the variable 'value' field in the query body to a concrete value
If you only want to test presence, switch the operation to 'exists' or 'notExists' which don't require a value
Ensure your client serializer doesn't drop or null out the value (e.g. omitEmptyBehaviour on a struct)

Example fix

// before
{"taskVariables":[{"name":"priority","operation":"equals"}]}
// after
{"taskVariables":[{"name":"priority","operation":"equals","value":50}]}

Defensive patterns

Strategy: validation

Validate before calling

// before sending a task query
function validateVar(v) {
  const noValueNeeded = ['exists','notExists'].includes(v.operation);
  if (!noValueNeeded && (v.value === undefined || v.value === null)) {
    throw new Error(`Variable '${v.name}' needs a value for operation '${v.operation}'`);
  }
}

Type guard

const hasValue = (v) => v != null && v.value != null;

Try / catch

try {
  const res = await flowable.queryTasks(body);
} catch (e) {
  if (e.message && e.message.includes('Variable value is missing')) {
    // fix request body: add value or switch to exists/notExists
  } else throw e;
}

Prevention

Never rely on omit-empty serialization for query variable values
Use 'exists'/'notExists' for presence checks instead of null comparisons
Validate query bodies against the Flowable REST schema before sending

When it happens

Trigger: POST/GET to /runtime/tasks (query) with a JSON variable filter like {"name":"x","operation":"equals","value":null}, or omitting the value field entirely while using equals/notEquals/like/greaterThan etc.

Common situations: Hand-written query bodies where the value key is forgotten; templated clients interpolating a null variable; scripts that strip empty JSON values; users copying EXISTS-style examples and forgetting to remove the value requirement.

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