flowable/flowable-engine · error · FlowableIllegalArgumentException

Error converting request body to RestVariable instance

Error message

Error converting request body to RestVariable instance

What it means

Thrown in updateVariable when the JSON body cannot be deserialized into a RestVariable object: Jackson throws during objectMapper.readValue(request.getInputStream(), RestVariable.class), and the resource wraps the exception in FlowableIllegalArgumentException. It means the request body is malformed or does not conform to the RestVariable schema.

Source

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

            @ApiParam(name = "variableName") @PathVariable("variableName") String variableName, HttpServletRequest request) {

        PlanItemInstance planItem = getPlanItemInstanceFromRequest(planItemInstanceId);

        RestVariable result = null;
        if (request instanceof MultipartHttpServletRequest) {
            result = setBinaryVariable((MultipartHttpServletRequest) request, planItem.getId(), CmmnRestResponseFactory.VARIABLE_PLAN_ITEM, false,
                    false, RestVariable.RestVariableScope.LOCAL, createVariableInterceptor(planItem));

            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, planItem.getId(), false, false, RestVariable.RestVariableScope.LOCAL, CmmnRestResponseFactory.VARIABLE_PLAN_ITEM, createVariableInterceptor(planItem));
        }
        return result;
    }
    
    @ApiOperation(value = "Update a variable on a plan item asynchronously", tags = { "Plan Item Instances" }, nickname = "updatePlanItemVariableAsync",
            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. Validate the body is well-formed JSON with the RestVariable shape: {"name":"...","type":"...","value":...}.
2. Set Content-Type: application/json on the request.
3. Confirm the value type matches one supported by RestVariableTypeConverter (string, integer, boolean, date ISO format, etc.).
4. Inspect the cause chain of the FlowableIllegalArgumentException for the exact Jackson deserialization message.

Example fix

// before
client.put(url, "value=42"); // form-encoded, not JSON
// after
client.putJson(url, "{\"name\":\"amount\",\"type\":\"integer\",\"value\":42}");

// validate before sending
const body = { name: variableName, type: 'integer', value: 42 };
JSON.parse(JSON.stringify(body)); // throws on circular/invalid payloads
if (!body.name) throw new Error('RestVariable requires name');

function isRestVariable(v) { return v !== null && typeof v === 'object' && typeof v.name === 'string' && 'value' in v; }

try { api.updateVariable(id, name, body); }
catch (FlowableIllegalArgumentException e) { logBodyForDebug(body); throw new Error('Malformed RestVariable body: ' + e.getCause(), e); }

When it happens

Trigger: PUT /cmmn-runtime/plan-item-instances/{id}/variables/{name} with a non-JSON body, invalid JSON syntax, missing Content-Type, or JSON that violates RestVariable structure (e.g. name/value fields of wrong type).

Common situations: Sending form-encoded or XML instead of JSON; trailing commas or unquoted keys; value objects Jackson cannot map; character-encoding issues corrupting the stream; proxy stripping 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

• request body could not be transformed to a RestVariable inst
• request body could not be transformed to a RestVariable inst
• Failed to serialize to a AttachmentRequest instance
• Error reading app resource
• Cannot aggregate overview variable: ${varInstance}

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