A workflow may not contain more than one workflow_return nod

Error message

A workflow may not contain more than one workflow_return node.

What it means

Workflow validation enforces that at most one node of type 'workflow_return' exists in a workflow. Multiple return nodes are ambiguous (which result should the workflow produce?), so the validator raises ValueError while parsing the nodes list.

Source

Thrown at invokeai/app/services/workflow_records/workflow_records_common.py:90

    # it is None.
    form: dict[str, JsonValue] | None = Field(default=None, description="The form of the workflow.")

    model_config = ConfigDict(extra="ignore")

    @field_validator("nodes")
    @classmethod
    def validate_workflow_return_node_uniqueness(cls, nodes: list[dict[str, JsonValue]]):
        workflow_return_count = 0

        for node in nodes:
            if not isinstance(node, dict) or node.get("type") != "invocation":
                continue
            data = node.get("data")
            if isinstance(data, dict) and data.get("type") == "workflow_return":
                workflow_return_count += 1

        if workflow_return_count > 1:
            raise ValueError("A workflow may not contain more than one workflow_return node.")

        return nodes


WorkflowWithoutIDValidator = TypeAdapter(WorkflowWithoutID)


class UnsafeWorkflowWithVersion(BaseModel):
    """
    This utility model only requires a workflow to have a valid version string.
    It is used to validate a workflow version without having to validate the entire workflow.
    """

    meta: WorkflowMeta = Field(description="The meta of the workflow.")


UnsafeWorkflowWithVersionValidator = TypeAdapter(UnsafeWorkflowWithVersion)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Remove the duplicate workflow_return node(s), keeping exactly one
Re-wire the second return's inputs into the single return node if both outputs are needed
Fix generator/merge code so it reuses one return node instead of appending new ones

Example fix

// before
nodes = [n1, return_node_a, return_node_b]
// after
nodes = [n1, return_node_a]  # delete or merge return_node_b

Defensive patterns

Strategy: validation

Validate before calling

def count_return_nodes(nodes: list[dict]) -> int:
    return sum(1 for n in nodes
               if isinstance(n.get("data"), dict) and n["data"].get("type") == "workflow_return")
assert count_return_nodes(workflow_dict["nodes"]) <= 1

Type guard

def has_single_return(nodes: object) -> bool:
    return isinstance(nodes, list) and count_return_nodes(nodes) == 1

Try / catch

try:
    wf = WorkflowWithoutID.model_validate(data)
except ValueError as e:
    if "workflow_return" in str(e):
        data["nodes"] = [n for n in data["nodes"] if not (isinstance(n.get("data"), dict) and n["data"].get("type") == "workflow_return")][:0] or dedupe_returns(data["nodes"])
        wf = WorkflowWithoutID.model_validate(data)
    else:
        raise

Prevention

When duplicating nodes in generated workflows, special-case workflow_return
Run validation on merged workflow JSON before saving
Keep a single template return node and rewire inputs instead of adding new ones

When it happens

Trigger: Loading or saving a WorkflowWithoutID/Workflow whose nodes contain two or more nodes with data.type == 'workflow_return'.

Common situations: Duplicating a node in the editor without deleting the original, merging two workflow JSON files, programmatic workflow generation that appends a return node per output.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/ce3eafc33aacc590. Report an issue: GitHub.