{"record":{"id":"023ff9da251135bd","repo":"flowable/flowable-engine","slug":"value-only-query-without-a-variable-name-is-only-023ff9","errorCode":null,"errorMessage":"Value-only query (without a variable-name) is only supported when using 'equals' operation.","messagePattern":"Value-only query \\(without a variable-name\\) is only supported when using 'equals' operation\\.","errorType":"http","errorClass":"FlowableIllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/BaseProcessInstanceResource.java","lineNumber":295,"sourceCode":"\n    protected void addVariables(ProcessInstanceQuery processInstanceQuery, List<QueryVariable> variables) {\n        for (QueryVariable variable : variables) {\n            if (variable.getVariableOperation() == null) {\n                throw new FlowableIllegalArgumentException(\"Variable operation is missing for variable: \" + variable.getName());\n            }\n            if (variable.getVariableOperation() != QueryVariableOperation.EXISTS && variable.getVariableOperation() != QueryVariableOperation.NOT_EXISTS) {\n                if (variable.getValue() == null) {\n                    throw new FlowableIllegalArgumentException(\"Variable value is missing for variable: \" + variable.getName());\n                }\n            }\n\n            boolean nameLess = variable.getName() == null;\n\n            Object actualValue = restResponseFactory.getVariableValue(variable);\n\n            // A value-only query is only possible using equals-operator\n            if (nameLess && variable.getVariableOperation() != QueryVariableOperation.EQUALS) {\n                throw new FlowableIllegalArgumentException(\"Value-only query (without a variable-name) is only supported when using 'equals' operation.\");\n            }\n\n            switch (variable.getVariableOperation()) {\n\n            case EQUALS:\n                if (nameLess) {\n                    processInstanceQuery.variableValueEquals(actualValue);\n                } else {\n                    processInstanceQuery.variableValueEquals(variable.getName(), actualValue);\n                }\n                break;\n\n            case EQUALS_IGNORE_CASE:\n                if (actualValue instanceof String) {\n                    processInstanceQuery.variableValueEqualsIgnoreCase(variable.getName(), (String) actualValue);\n                } else {\n                    throw new FlowableIllegalArgumentException(\"Only string variable values are supported when ignoring casing, but was: \" + actualValue.getClass().getName());\n                }","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/BaseProcessInstanceResource.java#L277-L313","documentation":"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.","triggerScenarios":"POST /runtime/process-instances/query with a variables entry that has a value and variableOperation like likeNot/greaterThan but \"name\": null or omitted.","commonSituations":"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.","solutions":["Add a \"name\" to the variable entry when using non-equals operations","Restrict name-less queries to \"variableOperation\":\"equals\"","Split the query: use equals for the value-only criterion and separate named criteria for other comparisons"],"exampleFix":"// before\n{\"variables\":[{\"value\":\"new\",\"variableOperation\":\"like\"}]}   // no name -> error\n// after\n{\"variables\":[{\"name\":\"status\",\"value\":\"new\",\"variableOperation\":\"like\"}]}","handlingStrategy":"validation","validationCode":"if (v.getName() == null && v.getVariableOperation() != QueryVariableOperation.EQUALS) throw new IllegalArgumentException(\"Nameless variable queries only support equals\");","typeGuard":"boolean isValueOnlyEquals(QueryVariable v) { return v.getName() == null && v.getVariableOperation() == QueryVariableOperation.EQUALS; }","tryCatchPattern":"try { client.queryProcessInstances(query); } catch (HttpClientErrorException e) { if (e.getResponseBodyAsString().contains(\"Value-only query\")) { /* add a name or switch to equals */ } }","preventionTips":["Always name variable criteria unless doing an any-variable-equals search","Constrain query builders to emit value-only filters only for equals","Document the equals-only rule for nameless queries in team guidelines"],"tags":["rest","query","validation"],"backgroundTag":"invalid-query-parameter","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T16:30:33.424Z"}