Gradio 6.20+: OSError: Cannot find empty port in range: 7861-7861.

问题场景

用户在 Hugging Face Spaces 上部署 Gradio 应用，升级至 Gradio 6.20+ 后，调用 demo.launch() 时抛出端口占用错误，无法启动 Space。原始应用为 Harmonic Melody MIDI Mixer，使用 Gradio Blocks 构建。

报错原文

Traceback (most recent call last):
  File "/app/app.py", line 484, in <module>
    demo.launch()
    ~~~~~~~~~~~^^
  File "/usr/local/lib/python3.13/site-packages/gradio/blocks.py", line 2952, in launch
    ) = http_server.start_server(
        ~~~~~~~~~~~~~~~~~~~~~~~~^
        app=self.app,
        ^^^^^^^^^^^^^
    ...<4 lines>...
        ssl_keyfile_password=ssl_keyfile_password,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/local/lib/python3.13/site-packages/gradio/http_server.py", line 182, in start_server
    raise OSError(
        f"Cannot find empty port in range: {min(server_ports)}-{max(server_ports)}. You can specify a different port by setting the GRADIO_SERVER_PORT environment variable or passing the `server_port` parameter to `launch()`."
    )
OSError: Cannot find empty port in range: 7861-7861. You can specify a different port by setting the GRADIO_SERVER_PORT environment variable or passing the `server_port` parameter to `launch`().

原因分析

可能原因：Hugging Face Spaces 底层容器中默认端口 7861 实际可用，但 Gradio 6.20+ 在检测端口时因账户 session 缓存异常（如 cookie 过期、认证令牌冲突）导致端口分配失败。用户最终发现登出并重新登录后问题消失，说明非 Gradio 自身 Bug，而是 Spaces 平台侧的凭据状态问题。

环境排查

• 确认 Gradio 版本是否为 6.20 或更高（6.21.0 测试后仍有个案失败）
• 确认 Hugging Face Spaces 是否使用默认端口 7861
• 检查浏览器是否有残留的 HF 账户 cookie 或会话信息
• 尝试在其他浏览器/无痕模式下访问同一 Space

解决步骤

1. 在浏览器中打开 Hugging Face 网站并登出当前账户（点击头像 → Sign Out）。
2. 清除浏览器缓存和 Cookie（或使用无痕/隐私窗口）。
3. 重新登录 Hugging Face 账户。
4. 进入 Space 页面，点击右上角 “Settings” → “Factory Rebuild”（重新从源码构建）。
5. 等待构建完成后点击 “Restart this Space” 或再次启动。
6. 若仍失败，可尝试手动设置端口：在应用代码的 launch() 中添加 server_port=7861，或在 Space 设置中添加环境变量 GRADIO_SERVER_PORT=7861（但 Issue 中用户未验证此方法）。

验证方法

重启 Space 后，观察 Gradio 应用是否正常显示界面，且无 OSError: Cannot find empty port 报错。点击界面按钮或拖动滑块验证交互是否响应。

参考来源

gradio-app/gradio #13693

AI 工具推荐

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

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

了解 GamsGo AI

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