flowable/flowable-engine · error · FlowableIllegalArgumentException

Failed to serialize to a RestVariable instance

Error message

Failed to serialize to a RestVariable instance

What it means

The bulk create-variables endpoint failed to deserialize the request InputStream into RestVariable objects. Any exception during readValue/convertValue (malformed JSON, wrong shape, bad types) is wrapped in FlowableIllegalArgumentException with this message.

Solutions

1. Validate the request body is well-formed JSON: an array of objects each with at least "name"
2. Send Content-Type: application/json
3. Test the payload with a JSON linter / curl before calling the API

Example fix

// before
["var1", "var2"]
// after
[{"name": "var1", "value": 1}, {"name": "var2", "value": 2}]

let parsed; try { parsed = JSON.parse(JSON.stringify(payload)); } catch (e) { throw new Error('Payload is not valid JSON: ' + e.message); } if (!Array.isArray(parsed) || !parsed.every(v => typeof v === 'object' && v !== null && v.name)) { throw new Error('Body must be an array of RestVariable objects'); }

function isRestVariableArray(v) { return Array.isArray(v) && v.every(x => typeof x === 'object' && x !== null && typeof x.name === 'string'); }

try { await api.post(`/runtime/tasks/${taskId}/variables`, payload); } catch (e) { if (e.response && e.response.status === 400 && /Failed to serialize/.test(e.response.data.message || '')) { logPayloadForDebug(payload); } throw e; }

When it happens

Trigger: POST /runtime/tasks/{taskId}/variables with a body that is not valid JSON or whose elements do not map to RestVariable (e.g. array of plain values instead of objects, unknown type identifiers, wrong Content-Type).

Common situations: Sending form-data or XML instead of JSON; passing [{"name":"v","value":1},{"x":2}] with malformed items; charset/BOM issues; custom variable types unregistered with the ObjectMapper.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Failed to serialize to a RestVariable instance
• An error occurs converting output value as JSon
• Cannot convert event payload
• Could not read json event payload
• Error converting request body to RestVariable instance

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

Appendix: source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/task/TaskVariableCollectionResource.java:145

        Object result = null;
        if (request instanceof MultipartHttpServletRequest) {
            result = setBinaryVariable((MultipartHttpServletRequest) request, task, true);
        } else {

            List<RestVariable> inputVariables = new ArrayList<>();
            List<RestVariable> resultVariables = new ArrayList<>();
            result = resultVariables;

            try {
                @SuppressWarnings("unchecked")
                List<Object> variableObjects = (List<Object>) objectMapper.readValue(request.getInputStream(), List.class);
                for (Object restObject : variableObjects) {
                    RestVariable restVariable = objectMapper.convertValue(restObject, RestVariable.class);
                    inputVariables.add(restVariable);
                }
            } catch (Exception e) {
                throw new FlowableIllegalArgumentException("Failed to serialize to a RestVariable instance", e);
            }

            if (inputVariables == null || inputVariables.size() == 0) {
                throw new FlowableIllegalArgumentException("Request did not contain a list of variables to create.");
            }

            RestVariableScope sharedScope = null;
            RestVariableScope varScope = null;
            Map<String, Object> variablesToSet = new HashMap<>();

            for (RestVariable var : inputVariables) {
                // Validate if scopes match
                varScope = var.getVariableScope();
                if (var.getName() == null) {
                    throw new FlowableIllegalArgumentException("Variable name is required");
                }

                if (varScope == null) {

View on GitHub (pinned to d6d39ce1c6)