flowable/flowable-engine · error · FlowableIllegalArgumentException

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

Error message

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

What it means

A nameless (value-only) variable filter — one with a null name, meaning 'any variable' — is only meaningful with the EQUALS operation. addVariables throws FlowableIllegalArgumentException if a nameless filter uses any other operation, since comparisons like GREATER_THAN without a name are undefined for the query builder.

Source

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

    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()) {

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

            case EQUALS_IGNORE_CASE:
                if (actualValue instanceof String) {
                    caseInstanceQuery.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)

Solutions

Use operation EQUALS for nameless value-only filters: {"value":"x","operation":"EQUALS"}.
Provide a variable name if you need other operations (LIKE, GREATER_THAN, etc.).
Use EXISTS/NOT_EXISTS with a name to test presence instead of a nameless non-equals filter.
Client-side validation: if name is null, force operation to EQUALS or reject the filter.

Example fix

// before
{"value":"active","operation":"LIKE"}

// after
{"value":"active","operation":"EQUALS"}  // nameless, or add "name" for LIKE

Defensive patterns

Strategy: validation

Validate before calling

if (v.name == null && v.operation !== 'EQUALS')
  throw new Error('Nameless variable filters require operation EQUALS');

Prevention

Force operation EQUALS when the filter has no name.
Give a name for any non-equals operator.
Reject empty name fields in query-builder UIs for non-equals operators.

When it happens

Trigger: Query variables entry such as {"value":"x","operation":"LIKE"} (no name field) or {"name":null,"operation":"NOT_EQUALS","value":"x"} in a case-instances query.

Common situations: Generic search UIs that omit names for 'search all variables' mode but pass through the user's chosen operator, template engines rendering empty name fields, or copying filters and clearing names.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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