flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable name is required

Error message

Variable name is required

What it means

FlowableIllegalArgumentException thrown by createTaskVariable when one of the RestVariable objects in the POST body has no name. The REST API requires every variable entry to carry an explicit name so it can be stored on the task's variable scope. This is a client payload validation failure, not a server fault.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/task/TaskVariableCollectionResource.java:161

                }
                
            } catch (Exception e) {
                throw new FlowableIllegalArgumentException("Failed to serialize to a RestVariable instance", e);
            }

            if (inputVariables == null || inputVariables.size() == 0) {
                throw new FlowableIllegalArgumentException("Request didn't contain a list of variables to create.");
            }

            RestVariableScope sharedScope = null;
            RestVariableScope varScope = null;
            Map<String, Object> variablesToSet = new HashMap<>();

            for (RestVariable var : inputVariables) {
                // Validate if scopes match
                varScope = var.getVariableScope();
                if (var.getName() == null) {
                    throw new FlowableIllegalArgumentException("Variable name is required");
                }

                if (varScope == null) {
                    varScope = RestVariableScope.LOCAL;
                }
                if (sharedScope == null) {
                    sharedScope = varScope;
                }
                if (varScope != sharedScope) {
                    throw new FlowableIllegalArgumentException("Only allowed to update multiple variables in the same scope.");
                }

                if (hasVariableOnScope(task, var.getName(), varScope)) {
                    throw new FlowableConflictException("Variable '" + var.getName() + "' is already present on task '" + task.getId() + "'.");
                }

                Object actualVariableValue = restResponseFactory.getVariableValue(var);
                variablesToSet.put(var.getName(), actualVariableValue);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure every element in the request body array has a non-null "name" field
2. Fix field-name typos so the JSON key is exactly "name"
3. Validate the payload client-side before sending
4. Send a single variable via the single-variable endpoint if body shape is easier to control

Example fix

// before
[{ "value": 42, "type": "integer" }]
// after
[{ "name": "count", "value": 42, "type": "integer" }]

const invalid = variables.some(v => v == null || typeof v.name !== 'string' || v.name.length === 0);
if (invalid) throw new Error('Every variable in the body requires a non-empty "name"');

function hasName(v) { return v != null && typeof v.name === 'string' && v.name.length > 0; }

try { await api.post(`/tasks/${taskId}/variables`, body); }
catch (e) { if (isFlowableIllegalArgument(e)) fixPayloadAndRetry(e); else throw e; }

When it happens

Trigger: POST to /cmmn-runtime/tasks/{taskId}/variables (or PUT variants routed through createTaskVariable) with a JSON body array where at least one element omits the "name" field or sets it to null.

Common situations: Hand-written JSON bodies with typos like "variableName" instead of "name"; programmatically built payloads where a variable object was constructed without a name; clients migrating from other REST APIs with different field names.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid reschedule timer action. Reschedule timer actions mu
• Variable name is required
• taskIds can not be null for bulk update tasks requests
• A group or a user is required to create an identity link.
• Either processDefinitionId, processDefinitionKey or message

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