{"record":{"id":"3529788db7e8221b","repo":"flowable/flowable-engine","slug":"failed-to-serialize-to-a-restvariable-instance","errorCode":null,"errorMessage":"Failed to serialize to a RestVariable instance","messagePattern":"Failed to serialize to a RestVariable instance","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/caze/BaseVariableResource.java","lineNumber":214,"sourceCode":"        Object result = null;\n        if (request instanceof MultipartHttpServletRequest) {\n            result = setBinaryVariable((MultipartHttpServletRequest) request, instanceId, variableType, true, async, scope, variableInterceptor);\n        } else {\n\n            List<RestVariable> inputVariables = new ArrayList<>();\n            List<RestVariable> resultVariables = new ArrayList<>();\n            result = resultVariables;\n\n            try {\n                @SuppressWarnings(\"unchecked\")\n                List<Object> variableObjects = (List<Object>) objectMapper.readValue(request.getInputStream(), List.class);\n                for (Object restObject : variableObjects) {\n                    RestVariable restVariable = objectMapper.convertValue(restObject, RestVariable.class);\n                    inputVariables.add(restVariable);\n                }\n                \n            } catch (Exception e) {\n                throw new FlowableIllegalArgumentException(\"Failed to serialize to a RestVariable instance\", e);\n            }\n\n            if (inputVariables == null || inputVariables.size() == 0) {\n                throw new FlowableIllegalArgumentException(\"Request didn't contain a list of variables to create.\");\n            }\n\n            Map<String, Object> variablesToSet = new HashMap<>();\n            for (RestVariable var : inputVariables) {\n                if (var.getName() == null) {\n                    throw new FlowableIllegalArgumentException(\"Variable name is required\");\n                }\n\n                Object actualVariableValue = restResponseFactory.getVariableValue(var);\n                variablesToSet.put(var.getName(), actualVariableValue);\n            }\n\n            if (!variablesToSet.isEmpty()) {\n                variableInterceptor.createVariables(variablesToSet);","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/caze/BaseVariableResource.java#L196-L232","documentation":"FlowableIllegalArgumentException thrown by createVariable when the JSON request body cannot be converted into RestVariable instances via Jackson's objectMapper.convertValue. The cause is a malformed or structurally wrong variables payload, not a domain-level validation failure.","triggerScenarios":"POST /cmmn-runtime/case-instances/{id}/variables with a body that is not a JSON array of variable objects (e.g. a map, a string, or objects with wrong-typed fields like \"value\": {complex object}).","commonSituations":"Clients send {\"variables\": [...]} wrapper (extra nesting) instead of a bare array; wrong Content-Type; value fields with types Jackson cannot map into RestVariable.","solutions":["Send a top-level JSON array: [{\"name\":\"x\",\"type\":\"string\",\"value\":\"y\"}, ...].","Ensure Content-Type is application/json.","Flatten the payload if wrapping variables in an extra object.","Inspect the wrapped exception cause to find the exact Jackson mapping failure."],"exampleFix":"// before\n{\"variables\": [{\"name\": \"a\", \"value\": \"b\"}]}\n// after\n[{\"name\": \"a\", \"type\": \"string\", \"value\": \"b\"}]","handlingStrategy":"validation","validationCode":"const body = JSON.stringify(vars.map(v => ({ name: v.name, type: v.type, value: v.value })));\nJSON.parse(body); // sanity check the array serializes\nif (!Array.isArray(vars) || vars.length === 0) throw new Error('variables must be a non-empty array');","typeGuard":"function isRestVariableArray(v) {\n  return Array.isArray(v) && v.every(x => x && typeof x.name === 'string');\n}","tryCatchPattern":"try {\n  await createVariables(id, vars);\n} catch (e) {\n  if (isIllegalArgument(e) && /Failed to serialize/.test(e.message)) throw new Error('Check request body is a JSON array of {name,type,value}');\n  throw e;\n}","preventionTips":["Always POST a top-level JSON array of variable objects, no wrapper key.","Keep Content-Type: application/json on the JSON variables endpoint.","Only include values Jackson can map (primitives, strings, dates, byte arrays)."],"tags":["rest","json","deserialization","request-body"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}