conductor-oss/conductor · error · NonTransientException

SubWorkflow name is null and no workflowDefinition supplied

Error message

SubWorkflow name is null and no workflowDefinition supplied

What it means

Thrown by the SubWorkflow task's start method when neither 'subWorkflowDefinition' (an inline WorkflowDef object) nor 'subWorkflowName' (a string referencing a registered workflow) is provided in the task input. The SUB_WORKFLOW task requires at least one of these to know which workflow to launch as a child.

Source

Thrown at core/src/main/java/com/netflix/conductor/core/execution/tasks/SubWorkflow.java:100

            resolvedVersion = version == 0 ? null : version;
        }

        WorkflowDef workflowDefinition = null;
        String name;
        if (input.get("subWorkflowDefinition") != null) {
            // Convert the runtime Map to a WorkflowDef. This supports both the static
            // embedded-object form and the dynamic ${expr}-resolved form.
            workflowDefinition =
                    objectMapper.convertValue(
                            input.get("subWorkflowDefinition"), WorkflowDef.class);
            name = workflowDefinition.getName();
        } else {
            name =
                    input.get("subWorkflowName") != null
                            ? input.get("subWorkflowName").toString()
                            : null;
            if (name == null) {
                throw new NonTransientException(
                        "SubWorkflow name is null and no workflowDefinition supplied");
            }
        }

        Map<String, String> taskToDomain = workflow.getTaskToDomain();
        if (input.get("subWorkflowTaskToDomain") instanceof Map) {
            taskToDomain = (Map<String, String>) input.get("subWorkflowTaskToDomain");
        }

        var wfInput = (Map<String, Object>) input.get("workflowInput");
        if (wfInput == null || wfInput.isEmpty()) {
            wfInput = input;
        }

        // Mark dynamically-generated sub-workflows so they can be identified downstream.
        if (workflowDefinition != null) {
            wfInput = new HashMap<>(wfInput);
            Map<String, Object> systemMetadata =

View on GitHub (pinned to cf7c3e4a8a)

Solutions

Add a 'subWorkflowName' field to the SUB_WORKFLOW task's subWorkflowParam pointing to a registered workflow definition name.
Alternatively, provide a complete 'subWorkflowDefinition' inline object with at least a 'name' field.
If using a dynamic ${...} expression for the sub-workflow name, verify the referenced source resolves to a non-null string at runtime.
Check the workflow definition JSON in the Conductor UI to confirm the subWorkflowParam block is present and correctly populated.

Example fix

// before
{
  "name": "call_child",
  "taskReferenceName": "call_child_ref",
  "type": "SUB_WORKFLOW",
  "subWorkflowParam": {
    "name": null
  }
}
// after
{
  "name": "call_child",
  "taskReferenceName": "call_child_ref",
  "type": "SUB_WORKFLOW",
  "subWorkflowParam": {
    "name": "child_workflow",
    "version": 1
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate SUB_WORKFLOW task config before workflow registration
for (WorkflowTask wt : workflowDef.collectTasks()) {
    if ("SUB_WORKFLOW".equals(wt.getType())) {
        SubWorkflowParams params = wt.getSubWorkflowParam();
        if (params == null
                || (params.getName() == null && params.getWorkflowDefinition() == null)) {
            throw new IllegalArgumentException(
                "SUB_WORKFLOW task '" + wt.getName()
                        + "' must have subWorkflowName or subWorkflowDefinition");
        }
    }
}

Prevention

Always populate subWorkflowParam.name with a registered workflow name in every SUB_WORKFLOW task.
Use a workflow-definition linter to catch missing subWorkflowParam before registration.
When using dynamic sub-workflow names, ensure the referenced input key always resolves to a non-null value.

When it happens

Trigger: Starting a SUB_WORKFLOW task whose inputParameters contain neither 'subWorkflowDefinition' nor 'subWorkflowName'. Also when subWorkflowName is present but resolves to null via a ${...} expression that evaluates to null.

Common situations: Misconfigured SUB_WORKFLOW task in the workflow definition — missing the subWorkflowParam entirely. A dynamic ${subWorkflowName} expression that resolves to null at runtime because the referenced value is absent. Copy-paste error where subWorkflowParam was renamed or removed.

Related errors

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/aa7dc94a161cb839. Report an issue: GitHub.