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

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.

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.

Appendix: 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)