flowable/flowable-engine · error · FlowableIllegalArgumentException

Value-only query (without a variable-name) is not supported

Error message

Value-only query (without a variable-name) is not supported

What it means

Thrown as FlowableIllegalArgumentException when a variable predicate omits the name (nameless, i.e. a 'value-only' query) and the operation is not EQUALS. The CMMN history REST API only supports value-only matching with the equals operator; any other operator needs a variable name to compare against. The request is rejected with HTTP 400.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/history/variable/HistoricVariableInstanceBaseResource.java:131

        }
    }

    protected void addVariables(HistoricVariableInstanceQuery variableInstanceQuery, List<QueryVariable> variables) {
        for (QueryVariable variable : variables) {
            if (variable.getVariableOperation() == null) {
                throw new FlowableIllegalArgumentException("Variable operation is missing for variable: " + variable.getName());
            }
            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()) {

            case EQUALS:
                variableInstanceQuery.variableValueEquals(variable.getName(), actualValue);
                break;

            default:
                throw new FlowableIllegalArgumentException("Unsupported variable query operation: " + variable.getVariableOperation());
            }
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. If doing a value-only match, restrict operation to "equals": {"value":"done","operation":"equals"}.
  2. If you need like/greaterThan/etc., supply a variable name: {"name":"status","value":"done","operation":"like"}.
  3. To find any variable with a given value regardless of name, iterate candidate names or fetch all instances and filter client-side; the query API does not support it.
  4. Validate filters before sending: nameless entries are only legal with operation equals.

Example fix

// before: 400 - nameless non-equals
{"variables":[{"value":"done","operation":"like"}]}

// after
{"variables":[{"name":"status","value":"done","operation":"equals"}]}
Defensive patterns

Strategy: validation

Validate before calling

boolean ok = variables.stream().allMatch(v -> v.getName() != null || "equals".equals(v.getOperation()));
if (!ok) { throw new IllegalArgumentException("nameless variable filters require operation equals"); }

Try / catch

try {
    HistoricVariableInstanceListResponse r = query(variables);
} catch (FlowableIllegalArgumentException e) {
    // HTTP 400: value-only query with non-equals operator
}

Prevention

When it happens

Trigger: Filter entry like {"value":"done","operation":"like"} or {"value":5,"operation":"greaterThan"} without "name" on the historic-variable-instances query endpoint.

Common situations: Porting queries from the BPMN engine API that allowed value-only equals and extending them to other operators, generic query-builder UIs that allow leaving the name blank, or intent to 'search any variable with value X using like' — which the historic variable query model cannot express.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

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