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

Thrown by updateVariable (PUT on a single case instance variable) when the variable name in the submitted body does not match the variableName taken from the request URL. Flowable enforces this consistency check to prevent ambiguous updates where the body targets a different variable than the endpoint addresses.

Source

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

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

        CaseInstance caseInstance = getCaseInstanceFromRequestWithoutAccessCheck(caseInstanceId);

        RestVariable result = null;
        if (request instanceof MultipartHttpServletRequest) {
            result = setBinaryVariable((MultipartHttpServletRequest) request, caseInstance.getId(), CmmnRestResponseFactory.VARIABLE_CASE, false,
                    false, RestVariable.RestVariableScope.GLOBAL, createVariableInterceptor(caseInstance));

            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, caseInstance.getId(), false, false, RestVariable.RestVariableScope.GLOBAL, CmmnRestResponseFactory.VARIABLE_CASE, createVariableInterceptor(caseInstance));

View on GitHub (pinned to d6d39ce1c6)

Solutions

Make the 'name' field in the request body exactly equal to the variableName segment in the URL.
If you meant to update a different variable, change the URL instead of the body name.
Omit a conflicting name if your client library auto-injects it, then let the URL define the name where the API allows it.

Example fix

// before: URL has 'orderCount' but body says 'quantity'
PUT /cmmn-runtime/case-instances/case1/variables/orderCount
{"name":"quantity","value":5,"type":"integer"}
// after: names match
PUT /cmmn-runtime/case-instances/case1/variables/orderCount
{"name":"orderCount","value":5,"type":"integer"}

Defensive patterns

Strategy: validation

Validate before calling

if (body.name !== variableName) {
  throw new Error(`Body name '${body.name}' must equal URL variable name '${variableName}'`);
}

Try / catch

try {
  await updateCaseVariable(caseId, variableName, body);
} catch (e) {
  if (e.status === 400) { /* align body.name with URL before retry */ }
  else throw e;
}

Prevention

Generate the body's 'name' field from the same variable used to build the URL.
Never copy-paste variable update bodies without updating 'name'.
Add a client-side assertion that body.name === urlVariableName.

When it happens

Trigger: PUT /cmmn-runtime/case-instances/{id}/variables/{variableName} where the parsed body (either the multipart binary variable or the JSON RestVariable) has a 'name' field different from {variableName} in the URL.

Common situations: Reusing a copy-pasted JSON body from a previous variable update without editing its 'name'; clients that build the body dynamically with one variable but interpolate another name into the URL; renaming a variable in code but not in stored request templates.

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