{"record":{"id":"01e185954abe1719","repo":"Comfy-Org/ComfyUI","slug":"invalid-return-type-from-node-type-to-return","errorCode":null,"errorMessage":"Invalid return type from node: {type(to_return)}","messagePattern":"Invalid return type from node: (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"comfy_api/latest/_io.py","lineNumber":2002,"sourceCode":"            return \"EXECUTE_NORMALIZED_ASYNC\"\n        return \"EXECUTE_NORMALIZED\"\n\n    @final\n    @classmethod\n    def EXECUTE_NORMALIZED(cls, *args, **kwargs) -> NodeOutput:\n        to_return = cls.execute(*args, **kwargs)\n        if to_return is None:\n            to_return = NodeOutput()\n        elif isinstance(to_return, NodeOutput):\n            pass\n        elif isinstance(to_return, tuple):\n            to_return = NodeOutput(*to_return)\n        elif isinstance(to_return, dict):\n            to_return = NodeOutput.from_dict(to_return)\n        elif isinstance(to_return, ExecutionBlocker):\n            to_return = NodeOutput(block_execution=to_return.message)\n        else:\n            raise Exception(f\"Invalid return type from node: {type(to_return)}\")\n        if to_return.expand is not None and not cls.SCHEMA.enable_expand:\n            raise Exception(f\"Node {cls.__name__} is not expandable, but expand included in NodeOutput; developer should set enable_expand=True on node's Schema to allow this.\")\n        return to_return\n\n    @final\n    @classmethod\n    async def EXECUTE_NORMALIZED_ASYNC(cls, *args, **kwargs) -> NodeOutput:\n        to_return = await cls.execute(*args, **kwargs)\n        if to_return is None:\n            to_return = NodeOutput()\n        elif isinstance(to_return, NodeOutput):\n            pass\n        elif isinstance(to_return, tuple):\n            to_return = NodeOutput(*to_return)\n        elif isinstance(to_return, dict):\n            to_return = NodeOutput.from_dict(to_return)\n        elif isinstance(to_return, ExecutionBlocker):\n            to_return = NodeOutput(block_execution=to_return.message)","sourceCodeStart":1984,"sourceCodeEnd":2020,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api/latest/_io.py#L1984-L2020","documentation":"ComfyUI normalizes every node's execute() return value into a NodeOutput, accepting None, NodeOutput, plain tuple, dict, or ExecutionBlocker. Anything else (an int, list, string, generator, ...) means the node author violated the return contract and the executor raises immediately instead of producing corrupt output.","triggerScenarios":"A custom node's execute returns e.g. a list comprehension of tensors, a bare string, or a numpy array — types accepted by legacy ComfyUI OUTPUT_NODE conventions but not by EXECUTE_NORMALIZED.","commonSituations":"Porting legacy nodes that returned lists; typos like 'return results' instead of 'return (results,)'; generators from comprehension refactors.","solutions":["Return a tuple matching RETURN_TYPES: `return (tensor,)`.","Or return a dict keyed by output names, or a NodeOutput, or None for no outputs.","Never return a raw list — convert with tuple(my_list)."],"exampleFix":"# before\ndef execute(self, ...):\n    return [img1, img2]  # list -> Exception\n\n# after\ndef execute(self, ...):\n    return (stack([img1, img2]),)  # tuple matching RETURN_TYPES","handlingStrategy":"type-guard","validationCode":"result = cls.execute(*args, **kwargs)\nassert result is None or isinstance(result, (NodeOutput, tuple, dict, ExecutionBlocker)), (\n    f\"bad return type {type(result)}\"\n)","typeGuard":"def valid_node_return(value) -> bool:\n    return value is None or isinstance(value, (NodeOutput, tuple, dict, ExecutionBlocker))","tryCatchPattern":null,"preventionTips":["Always return tuples matching RETURN_TYPES.","Convert lists with tuple(list) before returning.","Write a smoke test that calls execute and asserts the return type."],"tags":["comfyui","node-contract","return-type","custom-nodes","developer-error"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}