flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable operation is missing for variable: ${variable.getNa

Error message

Variable operation is missing for variable: ${variable.getName()}

What it means

FlowableIllegalArgumentException raised while building a historic case instance query from REST request variables: a QueryVariable entry has no 'operation' field set. The operation tells the engine how to compare the variable value, so it is mandatory.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/history/caze/HistoricCaseInstanceBaseResource.java:311

            restApiInterceptor.accessHistoryCaseInfoById(caseInstance);
        }
        
        return caseInstance;
    }

    protected HistoricCaseInstance getHistoricCaseInstanceFromRequestWithoutAccessCheck(String caseInstanceId) {
        HistoricCaseInstance caseInstance = historyService.createHistoricCaseInstanceQuery().caseInstanceId(caseInstanceId).singleResult();
        if (caseInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a case instance with id '" + caseInstanceId + "'.", HistoricCaseInstance.class);
        }

        return caseInstance;
    }

    protected void addVariables(HistoricCaseInstanceQuery caseInstanceQuery, 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()) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add the operation field to each variable object, e.g. {"name":"x","value":1,"operation":"equals"}
2. Use operation EXISTS/NOT_EXISTS for presence checks (value not required)
3. Validate the request body client-side before sending
4. Check client serialization maps the operation enum correctly

Example fix

// before
{"variables":[{"name":"status","value":"active"}]}
// after
{"variables":[{"name":"status","value":"active","operation":"equals"}]}

for (Map<String,Object> v : variables) {
  if (!v.containsKey("operation")) throw new IllegalArgumentException("Missing operation for variable " + v.get("name"));
}

boolean hasOperation(Map<String,Object> v) { return v.get("operation") != null; }

try { ... } catch (FlowableIllegalArgumentException e) {
  return badRequest("Invalid query variable: " + e.getMessage());
}

When it happens

Trigger: POST to the historic case instance query collection with a variable JSON object like {"name":"x","value":1} but no "operation" field (e.g. missing "operation":"equals").

Common situations: Hand-written JSON queries omitting 'operation'; client SDK upgrade changed the field name; copy-pasted payload that only included name/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: ${variable.getName()
• Variable operation is missing for variable:
• Value-only query (without a variable-name) is only supported
• Only string variable values are supported when ignoring casi
• Only string variable values are supported for like, but was:

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