flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable name is required.

Error message

Variable name is required.

What it means

FlowableIllegalArgumentException thrown by createProcessInstance when a RestVariable in the startFormVariables array has a null name. Start form variables are keyed by their name, so an anonymous entry cannot be applied to the form and the whole start request is rejected before the process instance is created. Each start form variable must carry a non-null name.

Source

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

        if (paramsSet > 1) {
            throw new FlowableIllegalArgumentException("Only one of processDefinitionId, processDefinitionKey or message should be set.");
        }

        if (request.isTenantSet()) {
            // Tenant-id can only be used with either key or message
            if (request.getProcessDefinitionId() != null) {
                throw new FlowableIllegalArgumentException("TenantId can only be used with either processDefinitionKey or message.");
            }
        }
        
        Map<String, Object> startVariables = null;
        Map<String, Object> transientVariables = null;
        Map<String, Object> startFormVariables = null;
        if (request.getStartFormVariables() != null && !request.getStartFormVariables().isEmpty()) {
            startFormVariables = new HashMap<>();
            for (RestVariable variable : request.getStartFormVariables()) {
                if (variable.getName() == null) {
                    throw new FlowableIllegalArgumentException("Variable name is required.");
                }
                startFormVariables.put(variable.getName(), restResponseFactory.getVariableValue(variable));
            }
        }

        if (request.getVariables() != null && !request.getVariables().isEmpty()) {
            startVariables = new HashMap<>();
            for (RestVariable variable : request.getVariables()) {
                if (variable.getName() == null) {
                    throw new FlowableIllegalArgumentException("Variable name is required.");
                }
                startVariables.put(variable.getName(), restResponseFactory.getVariableValue(variable));
            }
        }

        if (request.getTransientVariables() != null && !request.getTransientVariables().isEmpty()) {
            transientVariables = new HashMap<>();
            for (RestVariable variable : request.getTransientVariables()) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure every entry in startFormVariables has a non-null, non-empty 'name' field
2. Filter out blank/unnamed entries client-side before submitting
3. Build the array from a name->value map so names are always present
4. Validate the payload shape before the REST call

Example fix

// before
"startFormVariables":[{"type":"string","value":"Acme"}]
// after
"startFormVariables":[{"name":"customer","type":"string","value":"Acme"}]

for (const v of req.startFormVariables ?? []) {
  if (v.name == null || v.name === '') throw new Error('Every startFormVariables entry needs a non-empty name');
}

function allFormVarsNamed(vars) {
  return (vars ?? []).every(v => typeof v?.name === 'string' && v.name.length > 0);
}

try { await startProcessInstance(req); } catch (e) { if (e.status === 400 && /Variable name is required/.test(e.message)) { req.startFormVariables = req.startFormVariables.filter(v => v.name); } throw e; }

When it happens

Trigger: POST /runtime/process-instances with startFormVariables containing an entry like {"type":"string","value":"x"} (no name), typically when the array is built programmatically.

Common situations: Mapping form data where the key lives outside the object (e.g. [{value:...}] instead of a name/value map), serializers dropping null/empty name fields, UI code appending blank form rows that get submitted.

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

• Either processDefinitionId, processDefinitionKey or message
• Comment text is required.
• Variable operation is missing for variable: ${variable.getNa
• Variable value is missing for variable: ${variable.getName()
• Value-only query (without a variable-name) is not supported.

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