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

Set the 'name' property on every object in the transientVariables array

flowable/flowable-engine · error · FlowableIllegalArgumentException

Transient variable name is required

Error message

Transient variable name is required

What it means

FlowableIllegalArgumentException thrown by TaskResource.completeTask when an entry in the request's transientVariables array has no name. Transient variables are passed to the task completion builder and require an identifier. The REST API validates this before touching the engine.

Solutions

Set the 'name' property on every object in the transientVariables array
Validate the request payload client-side before calling the task action endpoint
If a variable is not meant to be transient, move it to the 'variables' array instead

Example fix

// before
{"action":"complete","transientVariables":[{"value":"x"}]}
// after
{"action":"complete","transientVariables":[{"name":"myVar","value":"x"}]}

Defensive patterns

Strategy: validation

Validate before calling

for (RestVariable v : actionRequest.getTransientVariables()) {
  if (v.getName() == null || v.getName().isEmpty()) throw new IllegalArgumentException("transient variable missing name");
}

Type guard

if (var != null && var.getName() != null && !var.getName().isEmpty()) { /* safe to send */ }

Try / catch

try { completeTask(...) } catch (FlowableIllegalArgumentException e) { log.error("Payload invalid: {}", e.getMessage()); }

Prevention

Map variables through a builder that enforces name on construction
Unit-test request payloads for required fields
Never hand-write variable JSON without a schema check

When it happens

Trigger: POST /runtime/tasks/{taskId}/action with action=complete and transientVariables containing an element whose name field is null/absent.

Common situations: Hand-built JSON payloads where a variable name key is misspelled (e.g. 'variable' instead of 'name'); dynamic payload construction that skips the name for one entry.

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

Appendix: source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/task/TaskResource.java:220

        if (actionRequest.getVariables() != null) {
            for (RestVariable var : actionRequest.getVariables()) {
                if (var.getName() == null) {
                    throw new FlowableIllegalArgumentException("Variable name is required");
                }

                Object actualVariableValue = restResponseFactory.getVariableValue(var);
                if (var.getVariableScope() != null && RestVariable.RestVariableScope.LOCAL.equals(var.getVariableScope())) {
                    taskCompletionBuilder.variableLocal(var.getName(), actualVariableValue);
                } else {
                    taskCompletionBuilder.variable(var.getName(), actualVariableValue);
                }
            }
        }

        if (actionRequest.getTransientVariables() != null) {
            for (RestVariable var : actionRequest.getTransientVariables()) {
                if (var.getName() == null) {
                    throw new FlowableIllegalArgumentException("Transient variable name is required");
                }

                Object actualVariableValue = restResponseFactory.getVariableValue(var);
                if (var.getVariableScope() != null && RestVariable.RestVariableScope.LOCAL.equals(var.getVariableScope())) {
                    taskCompletionBuilder.transientVariableLocal(var.getName(), actualVariableValue);
                } else {
                    taskCompletionBuilder.transientVariable(var.getName(), actualVariableValue);
                }
            }

        }

        taskCompletionBuilder
                .taskId(task.getId())
                .formDefinitionId(actionRequest.getFormDefinitionId())
                .outcome(actionRequest.getOutcome())
                .complete();
    }

View on GitHub (pinned to d6d39ce1c6)