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

Add a non-null 'name' to every object in the request's variables array.

flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable name is required.

Error message

Variable name is required.

What it means

FlowableIllegalArgumentException thrown by extractVariables in ExternalWorkerAcquireJobResource when completing, erroring (BPMN) or terminating (CMMN) an external worker job with a variable entry whose name is null. Variable payloads must carry a name to be persisted in the engine. The library fails fast instead of storing an unnamed variable.

Solutions

Add a non-null 'name' to every object in the request's variables array.
Validate the variables payload client-side before sending and reject entries with blank names.
Check the serialization code that produces EngineRestVariable instances to ensure the name property is populated.

Example fix

// before
{"variables":[{"type":"string","value":"approved"}]}
// after
{"variables":[{"name":"approved","type":"string","value":"approved"}]}

Defensive patterns

Strategy: validation

Validate before calling

if (body.getVariables() == null || body.getVariables().stream().anyMatch(v -> v.getName() == null || v.getName().isBlank())) {
    throw new IllegalArgumentException("every variable needs a name");
}

Type guard

boolean hasName(EngineRestVariable v) { return v != null && v.getName() != null && !v.getName().isEmpty(); }

Try / catch

try { completeJob(jobId, workerId, vars, transientVars); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().contains("Variable name")) { fixAndResendPayload(); } else { throw e; } }

Prevention

Always build variable payloads from key/value pairs so name is never null
Validate variable names client-side before posting
Use a typed DTO with a required name field

When it happens

Trigger: POST to the external worker completion/BPMN-error/CMMN-terminate endpoints (or calls to completeJob/bpmnErrorJob/terminateCmmnJob) with a request body whose 'variables' array contains an item without a 'name' field, or with name explicitly null.

Common situations: Hand-written JSON payloads where a variable object only has {"type":"string","value":"x"}; dynamic client code that builds variables from maps with null keys; deserialization dropping the name field due to mismatched DTO property naming.

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

Appendix: source

Thrown at modules/flowable-external-job-rest/src/main/java/org/flowable/external/job/rest/service/api/acquire/ExternalWorkerAcquireJobResource.java:278

            failureBuilder.retryTimeout(request.getRetryTimeout());
        }

        if (restApiInterceptor != null) {
            restApiInterceptor.failExternalWorkerJob(job, request);
        }

        failureBuilder.fail();

        return ResponseEntity.noContent().build();
    }

    protected Map<String, Object> extractVariables(List<EngineRestVariable> restVariables) {
        if (restVariables != null && !restVariables.isEmpty()) {
            Map<String, Object> variables = new HashMap<>();

            for (EngineRestVariable restVariable : restVariables) {
                if (restVariable.getName() == null) {
                    throw new FlowableIllegalArgumentException("Variable name is required.");
                }

                variables.put(restVariable.getName(), restResponseFactory.getVariableValue(restVariable));
            }

            return variables;
        }

        return Collections.emptyMap();
    }

    protected ExternalWorkerJobAcquireBuilder createExternalWorkerAcquireBuilder() {
        if (managementService != null) {
            return managementService.createExternalWorkerJobAcquireBuilder();
        } else if (cmmnManagementService != null) {
            return cmmnManagementService.createExternalWorkerJobAcquireBuilder();
        } else {
            throw new FlowableException("Cannot acquire external jobs. There is no BPMN or CMMN engine available");

View on GitHub (pinned to d6d39ce1c6)