{"record":{"id":"fd137c6ce380f932","repo":"flowable/flowable-engine","slug":"failed-to-serialize-to-a-restvariable-instance-fd137c","errorCode":null,"errorMessage":"Failed to serialize to a RestVariable instance","messagePattern":"Failed to serialize to a RestVariable instance","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/BaseVariableCollectionResource.java","lineNumber":101,"sourceCode":"    protected Object createExecutionVariable(Execution execution, boolean override, boolean async, HttpServletRequest request, HttpServletResponse response) {\n        Object result = null;\n        if (request instanceof MultipartHttpServletRequest) {\n            result = setBinaryVariable((MultipartHttpServletRequest) request, execution, true, async);\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            } 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 did not contain a list of variables to create.\");\n            }\n\n            RestVariableScope sharedScope = null;\n            RestVariableScope varScope = null;\n            Map<String, Object> variablesToSet = new HashMap<>();\n\n            for (RestVariable var : inputVariables) {\n                // Validate if scopes match\n                varScope = var.getVariableScope();\n                if (var.getName() == null) {\n                    throw new FlowableIllegalArgumentException(\"Variable name is required\");\n                }\n\n                if (varScope == null) {","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/BaseVariableCollectionResource.java#L83-L119","documentation":"BaseVariableCollectionResource.createExecutionVariable reads the request body and deserializes it into a List of RestVariable objects; any failure during readValue/convertValue is wrapped in this FlowableIllegalArgumentException with the underlying cause attached. It means the JSON payload is not a valid list of variable definitions.","triggerScenarios":"POSTing an array of variables to an execution/process-instance variables collection endpoint where items are missing required fields, have wrong types (e.g. \"value\" as an object without a type hint), or the body is not valid JSON at all.","commonSituations":"Malformed JSON from hand-built curl commands; sending {\"vars\":{...}} map-style payload where a list of RestVariable objects is expected; unsupported variable types that the Jackson converter cannot map to RestVariable.","solutions":["Inspect the wrapped cause exception (FlowableIllegalArgumentException#getCause) for the exact Jackson error","Send a JSON array of RestVariable objects: [{\"name\":\"x\",\"type\":\"integer\",\"value\":5}]","Validate the payload against the RestVariable schema (name, type, value, valueUrl, scope) before sending"],"exampleFix":"// before\n{\"name\":\"x\",\"value\":5}\n// after\n[{\"name\":\"x\",\"type\":\"integer\",\"value\":5}]","handlingStrategy":"validation","validationCode":"const vars = [{name:'x', type:'integer', value:5}]; JSON.parse(JSON.stringify(vars)); if (!Array.isArray(vars) || !vars.every(v => v && typeof v.name === 'string')) throw new Error('payload must be a list of RestVariable objects with names');","typeGuard":"function isRestVariableList(body) { return Array.isArray(body) && body.every(v => typeof v === 'object' && v !== null && typeof v.name === 'string'); }","tryCatchPattern":"try { await api.post(url, body); } catch (e) { if (e.message.includes('Failed to serialize to a RestVariable')) { console.error('Payload is not a valid RestVariable list:', e.cause || e); } }","preventionTips":["Always POST a JSON array, not a single object or a wrapper map","Provide explicit \"type\" for values Jackson cannot infer","Validate payloads against the REST API's documented variable schema before sending"],"tags":["flowable","rest-api","variables","json","serialization"],"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-14T11:17:12.474Z"}