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

When a QueryVariable has no name (a 'value-only query', meant to match plan item instances having ANY variable equal to the given value), Flowable restricts the operation to EQUALS. Any other operation (LIKE, GREATER_THAN, etc.) combined with a null name makes the query ambiguous, so addVariables throws FlowableIllegalArgumentException.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/planitem/PlanItemInstanceBaseResource.java:163

        return paginateList(requestParams, queryRequest, query, "createTime", allowedSortProperties, restResponseFactory::createPlanItemInstanceResponseList);
    }

    protected void addVariables(PlanItemInstanceQuery planItemInstanceQuery, List<QueryVariable> variables, boolean isCase) {
        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 (isCase) {
                        planItemInstanceQuery.caseVariableValueEquals(actualValue);
                    } else {
                        planItemInstanceQuery.variableValueEquals(actualValue);
                    }
                } else {
                    if (isCase) {
                        planItemInstanceQuery.caseVariableValueEquals(variable.getName(), actualValue);
                    } else {
                        planItemInstanceQuery.variableValueEquals(variable.getName(), actualValue);
                    }
                }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Set variableOperation to 'equals' when omitting the variable name.
  2. Add an explicit variable name if you need LIKE, NOT_EQUALS, or range comparisons.
  3. Validate name/operation combinations before sending the request.

Example fix

// before
{"name":null,"variableOperation":"like","value":"order%"}
// after
{"name":"orderNumber","variableOperation":"like","value":"order%"}
Defensive patterns

Strategy: validation

Validate before calling

if (!filters.every(f => f.name != null ? true : f.variableOperation === 'equals')) throw new Error('Nameless variable filters require equals');

Type guard

const isValueOnlyEquals = (f) => f.name == null && f.variableOperation === 'equals';

Try / catch

try { await query(body); } catch (e) { if (e.status === 400 && /Value-only query/.test(e.message)) { body.variables = body.variables.map(f => f.name ? f : {...f, variableOperation: 'equals'}); } else { throw e; } }

Prevention

When it happens

Trigger: Sending a plan-item-instance query with a variable filter where 'name' is null/absent and 'variableOperation' is anything other than 'equals' (e.g. like, notEquals, greaterThan).

Common situations: Copying a value-only example and changing the operation to 'like'; generic query builders that always omit the name field when the user didn't type one.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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