Studio 故障排除

Safari 连接问题

Safari 会阻止 localhost 上的纯 HTTP 流量。当使用 langgraph dev 运行 Studio 时，您可能会看到“Failed to load assistants”错误。

解决方案 1：使用 Cloudflare 隧道

Python
JS

pip install -U langgraph-cli>=0.2.6
langgraph dev --tunnel

# Requires @langchain/langgraph-cli>=0.0.26
npx @langchain/langgraph-cli dev --tunnel

该命令会输出一个隧道 URL。要连接 Studio：

复制隧道 URL（例如，https://hamilton-praise-heart-costumes.trycloudflare.com）
在 https://smith.langchain.com/studio/ 打开 Studio
点击 Connect to a local server
粘贴隧道 URL 并将其添加到 Allowed Origins
点击 Connect

出于安全考虑，此手动步骤是必需的 - Studio 在连接到外部 URL 之前需要明确的用户确认。

Cloudflare 隧道可能不可靠，并且可能会间歇性断开连接。

解决方案 2：使用 Chromium 浏览器

Chrome 和其他 Chromium 浏览器允许 localhost 上的 HTTP 连接。无需额外配置即可使用 langgraph dev。

Chrome 连接问题

从 Chrome 版本 142 开始，当您尝试通过 langgraph dev 将 LangSmith Studio 连接到本地开发服务器时，可能会遇到“Failed to initialize Studio”错误以及“TypeError: Failed to fetch”。即使 API 服务器 http://127.0.0.1:2024/docs 成功加载，也会发生此问题。 根本原因： Chrome 142 完全强制执行私有网络访问（PNA）规范，且没有回退机制，这默认会阻止 HTTPS 站点（如 https://smith.langchain.com）访问 HTTP localhost 服务器。

症状

运行 langgraph dev 成功启动服务器。
导航到 http://127.0.0.1:2024/docs 能正确显示 API 文档。
https://smith.langchain.com 上的 LangSmith Studio 显示：“Failed to initialize Studio - Please verify if the API server is running or accessible from the browser. TypeError: Failed to fetch”。
浏览器控制台显示类似错误：Permission was denied for this request to access the 'unknown' address space。

解决方案：在 Chrome 中允许本地网络访问

在 Chrome 中打开 https://smith.langchain.com 上的 LangSmith Studio。
点击地址栏左侧的锁形图标（或站点信息图标）。
在下拉菜单中查找 “Local network access” 选项。
将设置从 “Ask (default)” 或 “Block” 更改为 “Allow”。
重新加载页面。

现在 Studio 应该能成功连接到您的本地开发服务器。

其他故障排除

检查浏览器扩展冲突 浏览器扩展（尤其是 Ollama Chrome 扩展或 AI 模型扩展）可能会干扰 localhost 连接：

暂时禁用所有浏览器扩展。
重启 Chrome。
尝试再次连接到 Studio。
如果连接成功，逐个重新启用扩展以找出问题根源。

验证依赖项是否为最新版本

pip install -U "langgraph-cli[inmem]"

清除浏览器缓存和站点数据

在 Chrome 中，转到 Settings > Privacy and Security > Site Settings。
在列表中找到 https://smith.langchain.com。
点击 Clear data。
重启 Chrome 并重试。

Brave 连接问题

当启用 Brave Shields 时，Brave 会阻止 localhost 上的纯 HTTP 流量。当使用 langgraph dev 运行 Studio 时，您可能会看到“Failed to load assistants”错误。

解决方案 1：禁用 Brave 防护

使用 URL 栏中的 Brave 图标为 LangSmith 禁用 Brave Shields。

解决方案 2：使用 Cloudflare 隧道

Python
JS

pip install -U langgraph-cli>=0.2.6
langgraph dev --tunnel

# Requires @langchain/langgraph-cli>=0.0.26
npx @langchain/langgraph-cli dev --tunnel

该命令会输出一个隧道 URL。要连接 Studio：

复制隧道 URL（例如，https://hamilton-praise-heart-costumes.trycloudflare.com）
在 https://smith.langchain.com/studio/ 打开 Studio
点击 Connect to a local server
粘贴隧道 URL 并将其添加到 Allowed Origins
点击 Connect

出于安全考虑，此手动步骤是必需的 - Studio 在连接到外部 URL 之前需要明确的用户确认。

图边问题

未定义的条件边可能会在您的图中显示意外的连接。这是因为如果没有正确定义，Studio 会假定条件边可以访问所有其他节点。要解决此问题，请使用以下方法之一明确定义路由路径：

解决方案 1：路径映射

定义路由器输出与目标节点之间的映射：

Python
Javascript

graph.add_conditional_edges("node_a", routing_function, {True: "node_b", False: "node_c"})

graph.addConditionalEdges("node_a", routingFunction, { true: "node_b", false: "node_c" });

解决方案 2：路由器类型定义

使用 Python 的 Literal 类型指定可能的路由目标：

def routing_function(state: GraphState) -> Literal["node_b","node_c"]:
    if state['some_condition'] == True:
        return "node_b"
    else:
        return "node_c"

Studio 中的实验故障排除

Run experiment 按钮被禁用

检查以下内容：

已部署的应用程序：如果您的应用程序部署在 LangSmith 上，您可能需要创建一个新的修订版才能启用此功能。
本地开发服务器：如果您在本地运行应用程序，请确保您已升级到最新版本的 langgraph-cli（pip install -U langgraph-cli）。此外，请确保通过在项目的 .env 文件中设置 LANGSMITH_API_KEY 来启用追踪。

评估器结果缺失

当您运行实验时，任何附加的评估器都会被安排在队列中执行。如果您没有立即看到结果，很可能意味着它们仍在等待处理。

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Agent server

Core capabilities

Develop agents

Deployment guides

Studio

Auth & access control

Server customization

Safari 连接问题

解决方案 1：使用 Cloudflare 隧道

解决方案 2：使用 Chromium 浏览器

Chrome 连接问题

症状

解决方案：在 Chrome 中允许本地网络访问

其他故障排除

Brave 连接问题

解决方案 1：禁用 Brave 防护

解决方案 2：使用 Cloudflare 隧道

图边问题

解决方案 1：路径映射

解决方案 2：路由器类型定义

Studio 中的实验故障排除

Run experiment 按钮被禁用

评估器结果缺失

​Safari 连接问题

​解决方案 1：使用 Cloudflare 隧道

​解决方案 2：使用 Chromium 浏览器

​Chrome 连接问题

​症状

​解决方案：在 Chrome 中允许本地网络访问

​其他故障排除

​Brave 连接问题

​解决方案 1：禁用 Brave 防护

​解决方案 2：使用 Cloudflare 隧道

​图边问题

​解决方案 1：路径映射

​解决方案 2：路由器类型定义

​Studio 中的实验故障排除

​Run experiment 按钮被禁用

​评估器结果缺失

Safari 连接问题

解决方案 1：使用 Cloudflare 隧道

解决方案 2：使用 Chromium 浏览器

Chrome 连接问题

症状

解决方案：在 Chrome 中允许本地网络访问

其他故障排除

Brave 连接问题

解决方案 1：禁用 Brave 防护

解决方案 2：使用 Cloudflare 隧道

图边问题

解决方案 1：路径映射

解决方案 2：路由器类型定义

Studio 中的实验故障排除

Run experiment 按钮被禁用

评估器结果缺失