flowable/flowable-engine · error · FlowableIllegalArgumentException

Failed to serialize to a RestVariable instance

Error message

Failed to serialize to a RestVariable instance

What it means

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.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/caze/BaseVariableResource.java:214

        Object result = null;
        if (request instanceof MultipartHttpServletRequest) {
            result = setBinaryVariable((MultipartHttpServletRequest) request, instanceId, variableType, true, async, scope, variableInterceptor);
        } 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 didn't contain a list of variables to create.");
            }

            Map<String, Object> variablesToSet = new HashMap<>();
            for (RestVariable var : inputVariables) {
                if (var.getName() == null) {
                    throw new FlowableIllegalArgumentException("Variable name is required");
                }

                Object actualVariableValue = restResponseFactory.getVariableValue(var);
                variablesToSet.put(var.getName(), actualVariableValue);
            }

            if (!variablesToSet.isEmpty()) {
                variableInterceptor.createVariables(variablesToSet);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Send a top-level JSON array: [{"name":"x","type":"string","value":"y"}, ...].
2. Ensure Content-Type is application/json.
3. Flatten the payload if wrapping variables in an extra object.
4. Inspect the wrapped exception cause to find the exact Jackson mapping failure.

Example fix

// before
{"variables": [{"name": "a", "value": "b"}]}
// after
[{"name": "a", "type": "string", "value": "b"}]

const body = JSON.stringify(vars.map(v => ({ name: v.name, type: v.type, value: v.value })));
JSON.parse(body); // sanity check the array serializes
if (!Array.isArray(vars) || vars.length === 0) throw new Error('variables must be a non-empty array');

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

try {
  await createVariables(id, vars);
} catch (e) {
  if (isIllegalArgument(e) && /Failed to serialize/.test(e.message)) throw new Error('Check request body is a JSON array of {name,type,value}');
  throw e;
}

When it happens

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

Common situations: Clients send {"variables": [...]} wrapper (extra nesting) instead of a bare array; wrong Content-Type; value fields with types Jackson cannot map into 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

• request body could not be transformed to a RestVariable inst
• Error converting request body to RestVariable instance
• Error converting request body to RestVariable instance
• Error reading app resource
• Error writing form model response

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