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

FlowableIllegalArgumentException rejecting a value-only query condition (a variable with no name) in historic task instance queries. Unlike some runtime task query APIs, the historic task query does not support matching tasks purely by value without a variable name, so any nameless variable is invalid (HTTP 400).

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/history/task/HistoricTaskInstanceBaseResource.java:339

    protected void addTaskVariables(HistoricTaskInstanceQuery taskInstanceQuery, 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) {
                throw new FlowableIllegalArgumentException("Value-only query (without a variable-name) is not supported.");
            }

            switch (variable.getVariableOperation()) {

            case EQUALS:
                taskInstanceQuery.taskVariableValueEquals(variable.getName(), actualValue);
                break;

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

            case NOT_EQUALS:
                taskInstanceQuery.taskVariableValueNotEquals(variable.getName(), actualValue);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Always include the variable "name" in each variable condition: {"name":"owner","operation":"EQUALS","value":"kermit"}.
2. If you need 'any variable equals this value' semantics, issue one query per candidate variable name and merge results client-side.
3. Reject nameless variable conditions in your client before calling the API.
4. Check for client-side model bugs where the name field is lost during serialization.

Example fix

// before
{"value":"kermit","operation":"EQUALS"}
// after
{"name":"owner","value":"kermit","operation":"EQUALS"}

function validateQueryVars(vars) {
  for (const v of vars.taskVariableValues || []) {
    if (v.name === undefined || v.name === null) {
      throw new Error("value-only queries are not supported: add a variable name");
    }
  }
}

const hasName = (v) => typeof v.name === 'string' && v.name.length > 0;

When it happens

Trigger: POST /cmmn-history/historic-task-instances/query with a variable entry lacking the 'name' field, e.g. {"value":"kermit","operation":"EQUALS"}.

Common situations: Porting queries written for runtime task variable queries that allowed nameless value conditions; client models defaulting name to null; generic query builders omitting the name key.

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

• Variable operation is missing for variable: ${variable.getNa
• Variable value is missing for variable: ${variable.getName()
• Variable operation is missing for variable:
• Variable value is missing for variable:
• Variable value is missing for variable: {variableName}

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