ValueError: Returned component

快速结论：该报错通常发生在使用 gradio demo.py（热重载模式）运行 Gradio 应用时，在异步函数执行过程中修改源代码文件，导致旧函数输出组件与新 Demo 组件不匹配。优先排查是否在函数运行期间触发了热重载。

问题场景

用户使用 gradio script.py 命令启动 Gradio 应用（热重载模式），点击按钮触发一个异步耗时函数（如 asyncio.sleep(5) 或循环流式输出），在函数执行过程中修改并保存源代码文件（例如取消注释组件定义行）。应用前端显示 Connection errored out.，控制台反复打印 ValueError: Returned component ... not specified as output of function。即使组件设置了 key 属性（如 gr.Textbox(key="1")）也无法避免。

报错原文

ValueError: Returned component  not specified as output of function.

在流式输出场景下还可能伴随：

Traceback (most recent call last):
  ...
KeyError: 2

原因分析

这是热重载（hot-reload）机制与正在执行的函数之间的竞态条件（race condition）。Gradio 在检测到文件变更后会重建 Demo 对象并替换组件实例。但已经在队列中运行的旧函数仍然引用旧组件对象，当它尝试将计算结果映射到输出组件时，由于组件列表已被新 Demo 替换，旧组件对象无法在输出组件列表中找到匹配项，从而触发 ValueError。Issue 作者推测：函数仍然运行在旧 Demo 的上下文中，但组件已经原地更新为新 Demo 的组件。

竞态条件可能发生在不同的代码位置：

当映射组件到其 ID 时（blocks.py#L1671）
当解引用旧组件的 ID 时（blocks.py#L1711），此时可能触发 KeyError: 2

环境排查

确认 Gradio 版本：Issue 中为 4.37.2（gradio_client version: 1.0.2）
确认运行方式：使用 gradio demo.py 而非 python demo.py
确认函数是否包含耗时操作或流式输出（如 yield）
确认是否在函数执行期间手动保存了源代码文件

解决步骤

避免在函数执行期间修改代码：确保在触发任何事件/函数后，等待函数执行完毕（前端交互恢复）再修改和保存源文件。
使用 python demo.py 替代热重载模式：如果不需要自动重载功能，直接用 python demo.py 启动应用可完全避免此问题。
为输出组件设置唯一的 key 属性：虽然 Issue 中设置了 key 仍无法解决，但这是官方推荐的最佳实践，有助于未来版本的修复映射逻辑。
可优先尝试：升级到 Gradio 最新版本。Issue 关闭时间（2026-07-17）后可能已有修复。关于加锁（lock between reloading thread and function outputs）的讨论表明未来版本可能通过加锁机制解决。

验证方法

修改代码后，使用以下方式验证问题是否解决：

用 python demo.py 启动，点击按钮，确认不会出现报错
如必须使用热重载，确保在函数执行期间（前端显示“Processing”时）不修改任何源文件
升级 Gradio 后再次用热重载模式测试相同的竞态操作

参考来源

gradio-app/gradio #8712

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

ValueError: Returned component