What causes "Variable name is required" in flowable/flowable-engine?

Add the 'name' field to every variable object in the request body.

flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable name is required

Error message

Variable name is required

What it means

FlowableIllegalArgumentException thrown by ExecutionBaseResource.getVariablesToSet when a RestVariable in the request body has a null name. The REST variable-update endpoints require every variable object to identify which process variable it targets via its 'name' field; without it the variable cannot be mapped. This is a client-side request validation error, not a server failure.

Source

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

    protected Execution getExecutionFromRequest(String executionId) {
        Execution execution = runtimeService.createExecutionQuery().executionId(executionId).singleResult();
        if (execution == null) {
            throw new FlowableObjectNotFoundException("Could not find an execution with id '" + executionId + "'.", Execution.class);
        }
        
        if (restApiInterceptor != null) {
            restApiInterceptor.accessExecutionInfoById(execution);
        }
        
        return execution;
    }

    protected Map<String, Object> getVariablesToSet(List<RestVariable> restVariables) {
        Map<String, Object> variablesToSet = new HashMap<>();
        for (RestVariable var : restVariables) {
            if (var.getName() == null) {
                throw new FlowableIllegalArgumentException("Variable name is required");
            }

            Object actualVariableValue = restResponseFactory.getVariableValue(var);

            variablesToSet.put(var.getName(), actualVariableValue);
        }
        return variablesToSet;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Add the 'name' field to every variable object in the request body.
Check for field-name typos: the property must be 'name', not 'variableName' or 'key'.
Validate the payload client-side before sending (filter entries with null/blank names).
If constructing RestVariable objects in Java, call setName(...) before invoking the API.

Example fix

// before
[{"value": 5, "type": "integer"}]
// after
[{"name": "orderCount", "value": 5, "type": "integer"}]

Defensive patterns

Strategy: validation

Validate before calling

// JS/TS client-side check before POSTing variables
const invalid = variables.filter(v => !v || typeof v.name !== 'string' || v.name.length === 0);
if (invalid.length > 0) throw new Error('Every variable requires a non-empty "name" field');

Type guard

function hasName(v: unknown): v is { name: string; [k: string]: unknown } {
  return typeof v === 'object' && v !== null && typeof (v as any).name === 'string' && (v as any).name.length > 0;
}

Try / catch

try {
  await restClient.post(`/runtime/process-instances/${id}/variables`, variables);
} catch (e) {
  if (e.response && e.response.status === 400 && /Variable name is required/.test(e.response.data && e.response.data.message || '')) {
    console.error('Payload contains a variable without a name:', variables.filter(v => !v.name));
  }
  throw e;
}

Prevention

Always include 'name' in every variable object of REST payloads.
Build payloads from a validated map (Object.entries) so names cannot be dropped.
Write a shared payload serializer for Flowable variables instead of hand-writing JSON.
Add a unit test asserting every variable in generated payloads has a name.

When it happens

Trigger: POST/PUT to execution or process-instance variable endpoints (e.g. POST /runtime/process-instances/{id}/variables or PUT .../variables/{scope}) whose JSON body array contains an element without a 'name' field, e.g. [{"value": 5, "type": "integer"}].

Common situations: Hand-written JSON payloads omitting 'name'; scripts building variable arrays programmatically where a key is null or the field is misspelled ('variableName' instead of 'name'); deserialized RestVariable objects constructed in tests without setting name.

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

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