invoke-ai/InvokeAI · error · ValueError

Duplicate workflow return key '{key}'.

Error message

Duplicate workflow return key '{key}'.

What it means

The Workflow Return invocation collects named return values into a dict keyed by each value's 'key'. If two entries have the same (whitespace-stripped) key, the later value would silently overwrite the earlier one, so the library raises ValueError to force unique keys. This protects downstream Workflow Get invocations from resolving to the wrong value.

Source

Thrown at invokeai/app/invocations/workflow_return.py:100

class WorkflowReturnInvocation(BaseInvocation):
    """Defines the explicit named result returned by a callable workflow."""

    values: WorkflowReturnValueField | list[WorkflowReturnValueField] = InputField(
        default=[],
        description="The named values returned to a calling workflow.",
        title="Values",
        input=Input.Connection,
    )

    def invoke(self, context: InvocationContext) -> WorkflowReturnOutput:
        named_values: dict[str, Any] = {}
        return_values = self.values if isinstance(self.values, list) else [self.values]
        for value in return_values:
            key = value.key.strip()
            if not key:
                raise ValueError("Workflow return key must not be empty.")
            if key in named_values:
                raise ValueError(f"Duplicate workflow return key '{key}'.")
            named_values[key] = value.value
        return WorkflowReturnOutput(values=named_values)


@invocation_output("workflow_return_get_output")
class WorkflowReturnGetOutput(BaseInvocationOutput):
    """A value extracted from named workflow return values."""

    value: Any = OutputField(description="The extracted workflow return value.", title="Value", ui_type=UIType.Any)


@invocation(
    "workflow_return_get",
    title="Get Workflow Return Value",
    tags=["workflow", "return", "input"],
    category="workflow",
    version="1.0.0",
    classification=Classification.Beta,

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Open the workflow-return invocation and give each value a unique 'key' string
2. Strip/normalize keys in your workflow JSON to confirm the collision (keys differing only by surrounding whitespace still collide)
3. If two outputs genuinely share a name, nest them under distinct prefixes, e.g. 'image1' and 'image2'
4. Re-export/validate the workflow JSON programmatically to detect duplicates before running

Example fix

// before
values = [
  WorkflowReturnValue(key='image', value=img1),
  WorkflowReturnValue(key='image', value=img2),
]
// after
values = [
  WorkflowReturnValue(key='image_primary', value=img1),
  WorkflowReturnValue(key='image_secondary', value=img2),
]

def validate_return_keys(values):
    keys = [v.key.strip() for v in (values if isinstance(values, list) else [values])]
    dupes = {k for k in keys if keys.count(k) > 1}
    if dupes:
        raise ValueError(f"Duplicate workflow return keys: {sorted(dupes)}")
    if "" in keys:
        raise ValueError("Workflow return key must not be empty.")

try:
    output = invocation.invoke(context)
except ValueError as e:
    if "Duplicate workflow return key" in str(e):
        fix_duplicate_keys(workflow)
    else:
        raise

When it happens

Trigger: A workflow-return invocation whose 'values' list contains two WorkflowReturnValue entries with identical 'key' strings (after stripping whitespace); invoke() iterates the list and raises on the second occurrence.

Common situations: Duplicating a return node in the workflow editor and forgetting to rename the key; copying a node whose key field was copied verbatim; programmatic workflow JSON generation emitting the same key twice.

Related errors

• A saved workflow must be selected before executing call_save
• The selected saved workflow '${self.workflow_id}' could not
• Workflow return key must not be empty.
• Workflow return key '{key}' was not found.
• Unsupported batch group id '{batch_group_id}' in called work

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