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 when a query variable omits the name (a value-only search) but uses an operation other than equals. Searching 'any variable with this value' is only implemented for the equals operator.

Solutions

  1. Add the variable name to the predicate, keeping the desired operation.
  2. If a value-only search is intended, change the operation to "equals".
  3. Restrict the generic query builder to emit name-less variables only with equals.
  4. Catch FlowableIllegalArgumentException (HTTP 400) and fall back to a named equals query.

Example fix

// before
{"variables":[{"value":"42","operation":"like"}]}
// after
{"variables":[{"value":"42","operation":"equals"}]}
Defensive patterns

Strategy: validation

Validate before calling

for (const v of query.variables) {
  if ((v.name === undefined || v.name === null) && v.operation !== 'equals')
    throw new Error('Value-only query requires operation equals');
}

Type guard

const isValueOnlyEquals = (v) => (v.name == null) && v.operation === 'equals';

Try / catch

try { /* query */ } catch (e) {
  if (e.status === 400 && /Value-only query/.test(e.message)) {
    // retry with equals or add the variable name
  } else throw e;
}

Prevention

When it happens

Trigger: POST /query/process-instances with variables:[{"value":"42","operation":"like"}] (or notEquals, greaterThan, ignoreCase variants) and no name field.

Common situations: Generic query builders that treat variables uniformly and sometimes emit name-less predicates; user expects value-only search to work for all operators; migration from another engine whose query API allows it.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

        return paginateList(requestParams, queryRequest, query, "processInstanceId", allowedSortProperties, restResponseFactory::createExecutionResponseList);
    }

    protected void addVariables(ExecutionQuery processInstanceQuery, List<QueryVariable> variables, boolean process) {
        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 && 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) {
                    if (process) {
                        processInstanceQuery.processVariableValueEquals(actualValue);
                    } else {
                        processInstanceQuery.variableValueEquals(actualValue);
                    }
                } else {
                    if (process) {
                        processInstanceQuery.processVariableValueEquals(variable.getName(), actualValue);
                    } else {
                        processInstanceQuery.variableValueEquals(variable.getName(), actualValue);
                    }
                }

View on GitHub (pinned to d6d39ce1c6)