{"record":{"id":"3836d8ea7d12f9be","repo":"flowable/flowable-engine","slug":"variable-value-is-missing-for-variable-name","errorCode":null,"errorMessage":"Variable value is missing for variable: ${name}","messagePattern":"Variable value is missing for variable: (.+?)","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":409,"severity":"error","filePath":"modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/planitem/PlanItemInstanceBaseResource.java","lineNumber":154,"sourceCode":"\n        if (Boolean.TRUE.equals(queryRequest.getWithoutTenantId())) {\n            query.planItemInstanceWithoutTenantId();\n        }\n        \n        if (restApiInterceptor != null) {\n            restApiInterceptor.accessPlanItemInstanceInfoWithQuery(query, queryRequest);\n        }\n\n        return paginateList(requestParams, queryRequest, query, \"createTime\", allowedSortProperties, restResponseFactory::createPlanItemInstanceResponseList);\n    }\n\n    protected void addVariables(PlanItemInstanceQuery planItemInstanceQuery, List<QueryVariable> variables, boolean isCase) {\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.getValue() == null) {\n                throw new FlowableIllegalArgumentException(\"Variable value is missing for variable: \" + variable.getName());\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                    if (isCase) {\n                        planItemInstanceQuery.caseVariableValueEquals(actualValue);\n                    } else {","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/planitem/PlanItemInstanceBaseResource.java#L136-L172","documentation":"This FlowableIllegalArgumentException is thrown by the CMMN REST plan-item-instance query builder when a QueryVariable in the request has no value. The library requires every variable filter to carry both a name and a value (except EXISTS-style operations, which this endpoint does not support). It aborts the query before any query is executed rather than silently dropping the filter.","triggerScenarios":"Calling GET/POST on the CMMN plan-item-instance query endpoints (e.g. /cmmn-query/plan-item-instances) with a variable filter whose 'value' field is null or omitted, while 'name' and 'variableOperation' are set.","commonSituations":"Building the query JSON dynamically from a form or map where the value is an unset/null entry; client-side templating that renders '${name}' into the URL but skips the value; serialization bugs that drop null fields in an inconsistent way.","solutions":["Provide a non-null 'value' for every variable filter in the query request body or URL parameter.","If you intend to filter for existence rather than a concrete value, use an endpoint/query API that supports EXISTS/NOT_EXISTS (e.g. task query), not this plan-item-instance endpoint.","Validate the variable map client-side and remove entries with null values before building the request.","Catch FlowableIllegalArgumentException (HTTP 400) and surface which variable name was missing to the caller."],"exampleFix":"// before\n{\"name\":\"orderStatus\",\"variableOperation\":\"equals\",\"value\":null}\n// after\n{\"name\":\"orderStatus\",\"variableOperation\":\"equals\",\"value\":\"open\"}","handlingStrategy":"validation","validationCode":"if (vars.some(v => v.name == null || v.value == null)) throw new Error(\"Each variable filter needs name and value\");","typeGuard":"const hasValue = (v) => v != null && typeof v.name === 'string' && v.value != null;","tryCatchPattern":"try { const res = await queryPlanItemInstances(body); } catch (e) { if (e.status === 400 && /Variable value is missing/.test(e.message)) { /* fix payload */ } else { throw e; } }","preventionTips":["Never send variable filters with null values","Strip empty entries from the filter map before building the request","Unit-test query payload builders against null inputs"],"tags":["rest-api","query-parameters","validation"],"backgroundTag":"missing-required-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}