flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable operation is missing for variable:

Error message

Variable operation is missing for variable: 

What it means

addProcessVariables validates every QueryVariable in a historic task instance query. If variable.getVariableOperation() is null — i.e. the request did not specify an op at all — this FlowableIllegalArgumentException is thrown before any query is built. The operation is mandatory to know which query predicate to apply.

Source

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

            case EXISTS:
                taskInstanceQuery.taskVariableExists(variable.getName());
                break;

            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()) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add the operation segment to the variable query parameter, e.g. processVariable=equals==status/active.
2. In JSON query bodies, set "variableOperation": "equals" (or another supported op) on each QueryVariable.
3. Validate query-variable parameters client-side before sending to the REST API.

Example fix

// before
?processVariable=status/active
// after
?processVariable=equals==status/active

vars.forEach(v => { if (!v.variableOperation) throw new Error('Missing operation for variable ' + v.name); });

function hasOperation(v) { return typeof v.variableOperation === 'string' && v.variableOperation.length > 0; }

try { query(vars) } catch (e) { if (e instanceof FlowableIllegalArgumentException && e.message.startsWith('Variable operation is missing')) { /* fix payload */ } else throw e }

When it happens

Trigger: GET /history/historic-task-instances?processVariable=<name>/<value> without the <operation> segment, or a JSON body QueryVariable entry that omits the "operation" field.

Common situations: Omitting the op segment in the variable=... query-parameter shorthand; forgetting the operation property in POST query bodies; hand-written clients copying only name and value.

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 value is missing for variable:
• Unsupported variable query operation:
• Variable operation is missing for variable: ${variable.getNa
• Variable value is missing for variable: ${variable.getName()
• Variable operation is missing for variable:

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