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 request body cannot be deserialized by Jackson into a RestVariable object. The body must be valid JSON matching the RestVariable schema (at least {"name": ...}). The parse exception is preserved as the cause.

Source

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

        Task task = getTaskFromRequestWithoutAccessCheck(taskId);

        RestVariable result = null;
        if (request instanceof MultipartHttpServletRequest) {
            result = setBinaryVariable((MultipartHttpServletRequest) request, task, 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, task, false);
        }
        return result;
    }

    @ApiOperation(value = "Delete a variable on a task", tags = { "Task Variables" }, nickname = "deleteTaskInstanceVariable", code = 204)
    @ApiImplicitParams(@ApiImplicitParam(name = "scope", dataType = "string", value = "Scope of variable to be returned. When local, only task-local variable value is returned. When global, only variable value from the task’s parent execution-hierarchy are returned. When the parameter is omitted, a local variable will be returned if it exists, otherwise a global variable.", paramType = "query"))
    @ApiResponses(value = {
            @ApiResponse(code = 204, message = "Indicates the task variable was found and has been deleted. Response-body is intentionally empty."),

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Send a JSON object body like {"name":"x","value":42,"type":"integer"}
2. Set Content-Type: application/json
3. Check server logs for the nested Jackson cause to find the exact parse error
4. Validate the JSON body with a linter before sending

Example fix

// before
PUT .../variables/count   body: 42
// after
PUT .../variables/count   body: {"name":"count","value":42,"type":"integer"}

let parsed; try { parsed = JSON.parse(body); } catch (e) { throw new Error('Body must be valid JSON RestVariable object'); }
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new Error('Body must be a RestVariable JSON object');

function isRestVariable(b) { return b != null && typeof b === 'object' && !Array.isArray(b) && typeof b.name === 'string'; }

try { await api.put(url, body, { headers: {'Content-Type':'application/json'} }); }
catch (e) { if (/converting request body/i.test(e.message)) logAndInspectCause(e); else throw e; }

When it happens

Trigger: PUT /cmmn-runtime/tasks/{taskId}/variables/{name} with a non-JSON content type, malformed JSON, or a JSON value that is not an object (e.g. a bare string or number).

Common situations: Sending raw values ("42") instead of a RestVariable object; wrong Content-Type header causing the raw stream to be parsed; truncated bodies from proxy misconfiguration.

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
• Error converting request body to RestVariable instance
• Error reading app resource
• Error writing form model response
• request body could not be transformed to a RestVariable inst

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