flowable/flowable-engine · error · FlowableIllegalArgumentException

Value-only query (without a variable-name) is only…

Error message

Value-only query (without a variable-name) is only supported when using 'equals' operation.

What it means

FlowableIllegalArgumentException thrown by addVariables when a query variable has no name (value-only query) but its operation is not EQUALS. Omitting the name means 'match any variable with this value', which Flowable only supports for the equals operator.

Solutions

  1. Add a "name" to the variable entry when using non-equals operations
  2. Restrict name-less queries to "variableOperation":"equals"
  3. Split the query: use equals for the value-only criterion and separate named criteria for other comparisons

Example fix

// before
{"variables":[{"value":"new","variableOperation":"like"}]}   // no name -> error
// after
{"variables":[{"name":"status","value":"new","variableOperation":"like"}]}
Defensive patterns

Strategy: validation

Validate before calling

if (v.getName() == null && v.getVariableOperation() != QueryVariableOperation.EQUALS) throw new IllegalArgumentException("Nameless variable queries only support equals");

Type guard

boolean isValueOnlyEquals(QueryVariable v) { return v.getName() == null && v.getVariableOperation() == QueryVariableOperation.EQUALS; }

Try / catch

try { client.queryProcessInstances(query); } catch (HttpClientErrorException e) { if (e.getResponseBodyAsString().contains("Value-only query")) { /* add a name or switch to equals */ } }

Prevention

When it happens

Trigger: POST /runtime/process-instances/query with a variables entry that has a value and variableOperation like likeNot/greaterThan but "name": null or omitted.

Common situations: Generic query builders that leave name null for value filters; users expecting 'any variable like X' semantics which are unsupported; copy-paste of value-only equals example with a different operation.

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

Appendix: source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/BaseProcessInstanceResource.java:295

    protected void addVariables(ProcessInstanceQuery processInstanceQuery, 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()) {

            case EQUALS:
                if (nameLess) {
                    processInstanceQuery.variableValueEquals(actualValue);
                } else {
                    processInstanceQuery.variableValueEquals(variable.getName(), actualValue);
                }
                break;

            case EQUALS_IGNORE_CASE:
                if (actualValue instanceof String) {
                    processInstanceQuery.variableValueEqualsIgnoreCase(variable.getName(), (String) actualValue);
                } else {
                    throw new FlowableIllegalArgumentException("Only string variable values are supported when ignoring casing, but was: " + actualValue.getClass().getName());
                }

View on GitHub (pinned to d6d39ce1c6)