flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable operation is missing for variable: " + variable.get

Error message

Variable operation is missing for variable: " + variable.getName()

What it means

When building variable filters for a historic task instance query, each QueryVariable must declare a variableOperation. If it is null Flowable throws FlowableIllegalArgumentException because the query cannot know how to compare the variable. This is pure client request validation, thrown before any query executes.

Source

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

    }

    /**
     * Returns the {@link HistoricTaskInstance} that is requested without calling the access interceptor
     * 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()) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Set a valid operation on each variable filter, e.g. {"name":"x","operation":"equals","value":1}
  2. Check the operation string against the supported QueryVariableOperation values (equals, notEquals, equalsIgnoreCase, like, greaterThan, exists, etc.)
  3. Fix field name in the JSON payload so it deserializes into variableOperation

Example fix

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

Strategy: validation

Validate before calling

for (QueryVariable v : variables) {
    if (v.getVariableOperation() == null)
        throw new IllegalArgumentException("operation required for variable " + v.getName());
}

Prevention

When it happens

Trigger: POST query on /history/historic-tasks with a 'taskVariables' (or variables) entry whose 'operation' field is missing or misspelled (e.g. 'op' instead of 'operation'), producing addTaskVariables with a null operation.

Common situations: JSON body omits the operation property; client passes an operation string not mapped to QueryVariableOperation so the enum stays null; hand-built QueryVariable objects without setVariableOperation.

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