flowable/flowable-engine · error · FlowableIllegalArgumentException

Error converting request body to RestVariable instance

Error message

Error converting request body to RestVariable instance

What it means

FlowableIllegalArgumentException thrown by updateVariable when the JSON request body cannot be deserialized by Jackson into a RestVariable instance. The raw body is malformed JSON or does not conform to the RestVariable shape.

Source

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

        Execution execution = getExecutionFromRequestWithoutAccessCheck(executionId);

        RestVariable result = null;
        if (request instanceof MultipartHttpServletRequest) {
            result = setBinaryVariable((MultipartHttpServletRequest) request, execution, false, false);

            if (!result.getName().equals(variableName)) {
                throw new FlowableIllegalArgumentException("Variable name in the body should be equal to the name used in the requested URL.");
            }

        } else {

            RestVariable restVariable = null;

            try {
                restVariable = objectMapper.readValue(request.getInputStream(), RestVariable.class);
            } catch (Exception e) {
                throw new FlowableIllegalArgumentException("Error converting request body to RestVariable instance", e);
            }

            if (restVariable == null) {
                throw new FlowableException("Invalid body was supplied");
            }
            if (!restVariable.getName().equals(variableName)) {
                throw new FlowableIllegalArgumentException("Variable name in the body should be equal to the name used in the requested URL.");
            }

            result = setSimpleVariable(restVariable, execution, false, false);
        }
        return result;
    }
    
    @ApiOperation(value = "Update a variable on an execution asynchronously", tags = { "Executions" }, nickname = "updateExecutionVariableAsync",
            notes = "This endpoint can be used in 2 ways: By passing a JSON Body (RestVariable) or by passing a multipart/form-data Object.\n"
                    + "NB: Swagger V2 specification does not support this use case that is why this endpoint might be buggy/incomplete if used with other tools.")
    @ApiImplicitParams({

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Send a valid JSON body matching RestVariable: {"name":"...","type":"string","value":...} with Content-Type: application/json
2. Validate the JSON with a parser/linter before sending
3. Check that the 'type' field is a supported Flowable variable type name
4. Inspect the wrapped exception cause (e) in server logs for the exact Jackson deserialization error

Example fix

// before
name=status&value=active  (form-encoded)
// after
{"name":"status","type":"string","value":"active"} with Content-Type: application/json

const body = { name: variableName, type: inferFlowableType(value), value };
JSON.parse(JSON.stringify(body)); // throws if unserializable to valid JSON
headers["Content-Type"] = "application/json";

function isRestVariable(b) { return typeof b === "object" && b !== null && typeof b.name === "string" && (b.value === undefined ? false : "value" in b); }

try { return await updateVariable(id, name, body); }
catch (e) { if (e.status === 400 && /converting request body/i.test(e.message)) throw new Error("Invalid RestVariable JSON: " + e.message); throw e; }

When it happens

Trigger: PUT /runtime/executions/{id}/variables/{variableName} with a non-multipart body that is invalid JSON, wrong content type, or fields of the wrong type (e.g. 'value' as an object where a primitive/array is expected, or 'type' not resolvable).

Common situations: Sending form-encoded or plain text instead of JSON, unquoted or trailing-comma JSON, custom Java objects serialized inline that Jackson cannot map to RestVariable, charset/BOM issues in the body.

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
• Variable name is required
• 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/ea5575c034b12e05. Report an issue: GitHub.