invoke-ai/InvokeAI · error · ValueError

Workflow return key must not be empty.

Error message

Workflow return key must not be empty.

What it means

The single-value Workflow Return invocation exports one named key/value pair from a workflow. A whitespace-only or empty key would produce an unnamed return value that downstream consumers cannot reference, so InvokeAI raises ValueError after stripping the input.

Source

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

    version="1.0.0",
    classification=Classification.Beta,
    use_cache=False,
)
class WorkflowReturnValueInvocation(BaseInvocation):
    """Creates one named value for a callable workflow return."""

    key: str = InputField(default="", description="The return key.", title="Key")
    value: Any = InputField(
        default=None,
        description="The value returned under this key.",
        title="Value",
        ui_type=UIType.Any,
    )

    def invoke(self, context: InvocationContext) -> WorkflowReturnValueOutput:
        key = self.key.strip()
        if not key:
            raise ValueError("Workflow return key must not be empty.")
        return WorkflowReturnValueOutput(value=WorkflowReturnValueField(key=key, value=self.value))


@invocation(
    "workflow_return",
    title="Workflow Return",
    tags=["workflow", "return", "output"],
    category="workflow",
    version="1.0.0",
    classification=Classification.Beta,
    use_cache=False,
)
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.",

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Set a non-empty key, e.g. key = "result".
2. Trim intended whitespace-only keys to a real identifier.
3. If the key comes from a string node input, validate it is non-blank before feeding the node.

Example fix

// before
key = "   "  # strips to empty
// after
key = "result"

key = raw_key.strip()
if not key:
    raise ValueError("Workflow return key must not be empty.")

try:
    out = invocation.invoke(context)
except ValueError as e:
    if "key must not be empty" in str(e):
        key = "result"  # substitute a default key
    else:
        raise

When it happens

Trigger: Invoking the Workflow Return (single) node with key = "" or key = " " (strips to empty).

Common situations: Leaving the key field at its default/blank in the workflow editor; a workflow template where the key field was bound to an empty string node output.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• A saved workflow must be selected before executing call_save
• The selected saved workflow '${self.workflow_id}' could not
• Duplicate workflow return key '{key}'.
• 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/bf5fa285078601c6. Report an issue: GitHub.