flowable/flowable-engine · error · FlowableIllegalArgumentException

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

Error message

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

What it means

When updating a task variable via multipart (PUT /runtime/tasks/{taskId}/variables/{variableName}), Flowable reads the file's original filename/content as the variable name and compares it with the variableName in the URL. FlowableIllegalArgumentException is thrown if they differ. The REST API requires the body-embedded name to exactly match the URL path variable so there is no ambiguity about which variable is being written.

Source

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

            @ApiResponse(code = 200, message = "Indicates the variables was updated and the result is returned."),
            @ApiResponse(code = 400, message = "Indicates the name of a variable to update was missing or that an attempt is done to update a variable on a standalone task (without a process associated) with scope global. Status message provides additional information."),
            @ApiResponse(code = 404, message = "Indicates the requested task was not found or the task does not have a variable with the given name in the given scope. Status message contains additional information about the error."),
            @ApiResponse(code = 415, message = "Indicates the serializable data contains an object for which no class is present in the JVM running the Flowable engine and therefore cannot be deserialized."),
    })
    @PutMapping(value = "/runtime/tasks/{taskId}/variables/{variableName}", produces = "application/json", consumes = {"application/json", "multipart/form-data"})
    public RestVariable updateVariable(@ApiParam(name = "taskId") @PathVariable("taskId") String taskId,
            @ApiParam(name = "variableName") @PathVariable("variableName") String variableName,
            @ApiParam(hidden = true) @RequestParam(value = "scope", required = false) String scope,
            HttpServletRequest request) {

        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.");
            }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Make the multipart file part's name/filename exactly match the {variableName} in the URL.
Alternatively change the URL path to match the filename embedded in the request.
Strip path components/extensions client-side if the full filename is being sent but only the base name is expected.

Example fix

// before
curl -X PUT '.../tasks/123/variables/doc' -F 'file=@report.pdf'

// after
curl -X PUT '.../tasks/123/variables/report' -F 'file=@report.pdf'

Defensive patterns

Strategy: validation

Validate before calling

function validateMultipartVariableUpdate(urlVariableName, file) {
  const bodyName = file.name.replace(/\.[^.]+$/, ''); // adjust to API's extraction rule
  if (bodyName !== urlVariableName) {
    throw new Error(`multipart variable name '${bodyName}' must equal URL name '${urlVariableName}'`);
  }
}

Try / catch

try {
  return await putMultipart(url, formData);
} catch (e) {
  if (String(e.message).includes('should be equal to the name used in the requested URL')) {
    // retry with name derived from the file part
  }
  throw e;
}

Prevention

Derive the URL variable name from the uploaded file's name programmatically, not hardcoded.
Add a client-side assertion that filename and URL variable match before sending.
Rename files to the desired variable name before upload instead of divergent names.

When it happens

Trigger: PUT with multipart/form-data to /runtime/tasks/{taskId}/variables/{variableName} where the file part's name/filename (used as variable name) does not equal the {variableName} path segment.

Common situations: Uploading a file named 'report.pdf' while URL says variables/doc; renaming files but keeping hardcoded URL; tooling that sets the multipart part name to the field name instead of the variable name.

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/d4a178a5636ecd99. Report an issue: GitHub.