flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable name is required

Error message

Variable name is required

What it means

Guard in BaseVariableResource.createVariable: while converting the request payload to RestVariable(s), a variable object without a name was encountered; a variable cannot be stored on a case instance without a name.

Source

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

                @SuppressWarnings("unchecked")
                List<Object> variableObjects = (List<Object>) objectMapper.readValue(request.getInputStream(), List.class);
                for (Object restObject : variableObjects) {
                    RestVariable restVariable = objectMapper.convertValue(restObject, RestVariable.class);
                    inputVariables.add(restVariable);
                }
                
            } 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.");
            }

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

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

            if (!variablesToSet.isEmpty()) {
                variableInterceptor.createVariables(variablesToSet);
                Map<String, Object> setVariables = null;
                if (variableType == CmmnRestResponseFactory.VARIABLE_PLAN_ITEM || scope == RestVariableScope.LOCAL) {
                    if (async) {
                        runtimeService.setLocalVariablesAsync(instanceId, variablesToSet);
                        
                    } else {
                        runtimeService.setLocalVariables(instanceId, variablesToSet);
                        setVariables = runtimeService.getLocalVariables(instanceId, variablesToSet.keySet());
                    }
                    

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add a "name" property to every object in the variables array.
2. Validate client-side that each variable has a non-null name before sending.
3. Check for key typos ('Name', 'variableName') — the field must be exactly "name".

Example fix

// before
[{"type": "string", "value": "x"}]
// after
[{"name": "status", "type": "string", "value": "x"}]

const bad = vars.filter(v => !v.name);
if (bad.length) throw new Error(`Every variable needs a name; ${bad.length} missing`);

function allNamed(vars) {
  return Array.isArray(vars) && vars.every(v => typeof v.name === 'string' && v.name.length > 0);
}

try {
  await createVariables(id, vars);
} catch (e) {
  if (/Variable name is required/.test(e.message)) throw new Error('One of the variables lacks a "name" field');
  throw e;
}

When it happens

Trigger: POST .../variables with an entry like {"type":"string","value":"x"} — name is null.

Common situations: Hand-written JSON omitting 'name'; programmatically built payloads where null-named entries slip in; renaming a field to 'variableName' by mistake.

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

• Variable '${restVariable.getName()}' has unsupported type: '
• Invalid variable scope: '${scope}'
• Variable operation is missing for variable:
• Invalid reschedule timer action. Reschedule timer actions mu
• Request didn't contain a list of variables to create.

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