flowable/flowable-engine · error · FlowableIllegalArgumentException

Failed to serialize to a RestVariable instance

Error message

Failed to serialize to a RestVariable instance

What it means

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.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/BaseVariableCollectionResource.java:101

    protected Object createExecutionVariable(Execution execution, boolean override, boolean async, HttpServletRequest request, HttpServletResponse response) {
        Object result = null;
        if (request instanceof MultipartHttpServletRequest) {
            result = setBinaryVariable((MultipartHttpServletRequest) request, execution, true, async);
        } 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)

Solutions

1. Inspect the wrapped cause exception (FlowableIllegalArgumentException#getCause) for the exact Jackson error
2. Send a JSON array of RestVariable objects: [{"name":"x","type":"integer","value":5}]
3. Validate the payload against the RestVariable schema (name, type, value, valueUrl, scope) before sending

Example fix

// before
{"name":"x","value":5}
// after
[{"name":"x","type":"integer","value":5}]

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');

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

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); } }

When it happens

Trigger: 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.

Common situations: 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.

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

• Error writing app model to json
• Variable name in the body should be equal to the name used i
• request body could not be transformed to a RestVariable inst
• Invalid body was supplied
• Failed to parse jase

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