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

When querying case instances with variable filters, each QueryVariable must declare a variableOperation (equals, notEquals, like, etc.). addVariables validates this and throws FlowableIllegalArgumentException when the operation is missing, since the engine cannot translate the filter into a query predicate.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/caze/BaseCaseInstanceResource.java:304

    }

    /**
     * Returns the {@link CaseInstance} that is requested without calling the access interceptor
     * Throws the right exceptions when bad request was made or instance was not found.
     */
    protected CaseInstance getCaseInstanceFromRequestWithoutAccessCheck(String caseInstanceId) {
        CaseInstance caseInstance = runtimeService.createCaseInstanceQuery().caseInstanceId(caseInstanceId).singleResult();
        if (caseInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a case instance with id '" + caseInstanceId + "'.");
        }

        return caseInstance;
    }

    protected void addVariables(CaseInstanceQuery 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

Add the operation field to each variable filter, e.g. {"name":"state","value":"active","operation":"EQUALS"}.
Use a supported QueryVariableOperation value (EQUALS, NOT_EQUALS, EQUALS_IGNORE_CASE, LIKE, GREATER_THAN, LESS_THAN, EXISTS, NOT_EXISTS, ...).
Validate variable filter objects client-side before sending the query.
Check that your client serializer includes the operation field (nulls may be dropped).

Example fix

// before
{"variables": [{"name": "state", "value": "active"}]}

// after
{"variables": [{"name": "state", "value": "active", "operation": "EQUALS"}]}

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Always include operation in every variables[] entry of query bodies.
Use only documented QueryVariableOperation values.
Validate filter objects before serialization.

When it happens

Trigger: POST/PUT query requests to /cmmn-query/runtime/case-instances (via getQueryResponse) whose body contains a variables array entry without the required 'operation' field, e.g. {"name":"state","value":"active"}.

Common situations: Hand-written JSON queries omitting the operation key, client DTOs that don't map the operation field, API version differences where the field name changed, or null operation after enum parsing of an unknown operation string.

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