flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable name in the body should be equal to the name used…

Error message

Variable name in the body should be equal to the name used in the requested URL.

What it means

Flowable REST throws FlowableIllegalArgumentException when updating a process instance variable if the variable name in the request body (or uploaded file form field) differs from the {variableName} in the URL. Name in body and URL must match exactly.

Solutions

Set the body 'name' property (or multipart field name) to exactly the URL variable name.
Regenerate request bodies from the URL instead of reusing old payloads.
Match casing exactly — the comparison is case-sensitive.

Example fix

// PUT /runtime/process-instances/123/variables/orderAmount
// before
{"name":"orderamount","type":"integer","value":5}
// after
{"name":"orderAmount","type":"integer","value":5}

Defensive patterns

Strategy: validation

Validate before calling

if (body.name !== urlVariableName) throw new Error('body name must equal URL variable name: ' + urlVariableName);

Type guard

const namesMatch = (body, urlName) => body != null && typeof body.name === 'string' && body.name === urlName;

Prevention

Generate the body from the same variable constant used in the URL
For multipart uploads, set the form field name to the URL variable name
Watch for case mismatches

When it happens

Trigger: PUT /runtime/process-instances/{id}/variables/{name} where the multipart file field name or the 'name' property in the JSON body differs from {name} (case-sensitive comparison).

Common situations: Copy-pasted request bodies where only the URL was edited; multipart uploads where the form field defaults to 'file' while URL names another variable; case mismatch ('OrderAmount' vs 'orderAmount').

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

            @ApiImplicitParam(name = "name", dataType = "string", paramType = "form", example = "Simple content item"),
            @ApiImplicitParam(name = "type", dataType = "string", paramType = "form", example = "integer"),
    })
    @ApiResponses(value = {
            @ApiResponse(code = 201, message = "Indicates both the process instance and variable were found and variable is updated."),
            @ApiResponse(code = 404, message = "Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.")
    })
    @PutMapping(value = "/runtime/process-instances/{processInstanceId}/variables/{variableName}", produces = "application/json", consumes = {"application/json", "multipart/form-data"})
    public RestVariable updateVariable(@ApiParam(name = "processInstanceId") @PathVariable("processInstanceId") String processInstanceId, @ApiParam(name = "variableName") @PathVariable("variableName") String variableName,
            HttpServletRequest request) {

        Execution execution = getExecutionFromRequestWithoutAccessCheck(processInstanceId);

        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("request body could not be transformed to a 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);

View on GitHub (pinned to d6d39ce1c6)