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 createTaskVariable when the JSON array of variable objects in the request body cannot be converted to RestVariable instances via Jackson's objectMapper.convertValue. Any structural mismatch (wrong element shapes, unexpected field types) is caught and rethrown with this message and the underlying exception as cause.

Source

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

        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 didn't 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. Send an array of RestVariable-shaped objects: [{"name":"..","type":"..","value":..}]
2. Inspect the cause in the server log for the exact Jackson path error
3. Validate JSON structure against the Flowable REST variable schema before sending
4. Ensure Content-Type is application/json

Example fix

// before
{"variables": "name1"}
// after
{"variables": [{"name":"name1","type":"string","value":"x"}]}

const isRestVariable = (v) => v != null && typeof v === 'object' && !Array.isArray(v) && typeof v.name === 'string';
if (!Array.isArray(vars) || !vars.every(isRestVariable)) throw new Error('variables must be an array of {name,type,value} objects');

const isRestVariable = (v) => v != null && typeof v === 'object' && !Array.isArray(v) && typeof v.name === 'string';

try { await createVariables(payload) } catch (e) { if (/Failed to serialize to a RestVariable/.test(e.message)) console.error('malformed variable payload', e.cause); throw e; }

When it happens

Trigger: POST /cmmn-runtime/tasks/{taskId}/variables with a body whose 'variables' array contains elements that don't map to RestVariable — e.g. a bare string instead of an object, or fields with incompatible value types.

Common situations: Clients posting single objects instead of arrays; wrong JSON shape due to library version changes; copy-paste errors mixing the binary and JSON endpoints; non-JSON content types.

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 form model response
• Variable name is required
• Cannot get variable value for jackson 2
• Multipart request is required
• Multipart request with file content is required

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