跳到主要内容

Langflow 故障排除 (Troubleshoot Langflow)

本页为使用 Langflow 或为 Langflow 做出贡献时可能遇到的问题提供故障排除建议。

组件缺失 (Missing components)​

随着 Langflow 的不断开发，组件经常会被重新分类或弃用，以便更好地对齐或为新组件做准备。

如果组件似乎从 核心组件 (Core components) 菜单中消失了，请尝试以下操作：

如果您仍然找不到该组件，请参阅 Langflow GitHub 问题和讨论。

游乐场中没有输入框 (No input in the Playground)​

如果 游乐场 (Playground) 中没有消息输入字段，请确保您的流中有一个 聊天输入 (Chat Input) 组件，该组件直接或间接地连接到 语言模型 (Language Model) 或 代理 (Agent) 组件的 输入 (Input) 端口。

因为 游乐场 旨在用于使用 LLM 进行查询和响应格式的流（例如聊天机器人和代理），所以流必须具有 聊天输入 (Chat Input)、语言模型 (Language Model)/代理 (Agent) 和 聊天输出 (Chat Output) 组件，才能受到 游乐场 聊天界面的完整支持。

更多信息请参阅 在游乐场中测试流。

密钥丢失、找不到密钥或 API 密钥无效 (Missing key, no key found, or invalid API key)​

如果在运行流时遇到 API 密钥错误，请尝试以下操作：

  • 对于所有需要凭据的组件，确保这些组件在组件设置中具有有效的凭据，例如 API Key 字段。
  • 如果您将凭据存储在 Langflow 全局变量 中，请确保选择了正确的全局变量，并且该变量包含有效的凭据。
  • 确保提供的凭据处于激活状态，具有所需的权限，并且在适用情况下，账户中有足够的资金来执行所需的操作。例如，模型提供商需要积分才能使用其 LLM。

Langflow 安装问题 (Langflow installation issues)​

安装 Langflow 时可能会出现以下问题。

Langflow 安装在 pip 依赖解析处卡住 (Langflow installation freezes at pip dependency resolution)​

使用 pip install langflow 安装 Langflow OSS 时，可能会出现以下错误消息并缓慢失败：


_10
pip is looking at multiple versions of <<library>> to determine which version is compatible with other requirements. This could take a while.

要解决此问题，请使用 uv 而不是 pip 来安装 Langflow，如 安装并运行 Langflow OSS Python 包 中所述。

Linux 安装未能构建所需包 (Linux installation fails to build required package)​

当您尝试在 Linux 上安装 Langflow OSS 时，安装可能会因为包过时或缺失而失败：


_10
Resolved 455 packages in 18.92s
_10
× Failed to build `webrtcvad==2.0.10`
_10
├─▶ The build backend returned an error
_10
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)

要解决此错误，请安装所需的构建依赖项，然后重试 Langflow 安装：


_10
sudo apt-get update
_10
sudo apt-get install build-essential python3-dev

如果升级包不能解决问题，请单独安装 gcc，然后重试 Langflow 安装：


_10
sudo apt-get install gcc

webrtcvad 包导致的安装失败 (Installation failure from webrtcvad package)​

如果您遇到来自 webrtcvad 包的错误，请在您的虚拟环境中运行 uv pip install webrtcvad-wheels，然后重试 Langflow 安装。

Windows 上 Langflow Desktop 需要 C++ 构建工具 (C++ build tools required for Langflow Desktop on Windows)​

在 Microsoft Windows 上安装 Langflow Desktop 需要您的系统上可能不存在的 C++ 编译器。如果您收到 C++ Build Tools Required! 错误，请按照屏幕提示安装 Microsoft C++ 构建工具，或 安装 Microsoft Visual Studio。

Langflow 启动问题 (Langflow startup issues)​

尝试启动 Langflow 时可能会出现以下问题。

无 langflow.__main__ 模块 (No langflow.__main__ module)​

当您尝试使用命令 langflow run 运行 Langflow 时，遇到以下错误：


_10
> No module named 'langflow.__main__'

要解决此问题，请尝试以下操作：

  1. 运行 uv run langflow run 而不是 langflow run。
  2. 如果不起作用，请使用 uv pip install langflow -U 重新安装最新的 Langflow 版本。
  3. 如果仍不起作用，请使用 uv pip install langflow --pre -U --force-reinstall 重新安装 Langflow 及其依赖项。

Langflow runTraceback​

当您尝试使用命令 langflow run 运行 Langflow 时，遇到以下错误：


_10
> langflow runTraceback (most recent call last): File ".../langflow", line 5, in <module> from langflow.__main__ import mainModuleNotFoundError: No module named 'langflow.__main__'

此错误有两个可能的原因：

  • 多个 Langflow 安装：您使用 pip install langflow 安装了 Langflow，但系统中已经安装了以前版本的 Langflow。在这种情况下，您运行的可能是错误的可执行文件。

    要解决此问题，请通过运行 python -m langflow run 而不是 langflow run 来运行正确的可执行文件。

    如果不起作用，请尝试使用 uv pip install langflow --pre -U 卸载并重新安装 Langflow。

  • 安装期间的版本冲突：安装过程中可能发生了一些版本冲突。要解决此问题，请通过运行 python -m pip install langflow --pre -U --force-reinstall 重新安装 Langflow 及其依赖项。

终端中无法使用环境变量 (Environment variables not available from terminal)​

在终端中设置的环境变量不会自动对通过访达 (Finder) 或开始菜单启动的 Langflow Desktop 等基于 GUI 的应用程序生效。 要为 Langflow Desktop 设置环境变量，请参阅 为 Langflow Desktop 设置环境变量。

访问 Langflow Desktop 启动日志 (Access Langflow Desktop startup logs)​

如果您在使用 Langflow Desktop 时遇到问题，可能需要 访问 Langflow Desktop 启动日志 进行调试。

运行多个流时提示用户未找到或处于非活动状态 (User not found or inactive when running multiple flows)​

当在不同端口运行多个本地 Langflow OSS 实例时（例如 localhost:7860 和 localhost:7861），您可能会在日志中看到身份验证错误。 例如：


_10
[07/22/25 10:57:07] INFO 2025-07-22 10:57:07 - INFO - utils - User not found or inactive.

要解决此错误，请使用单独的浏览器实例或浏览器配置文件来访问每个 Langflow 实例。

软件包未安装 (Package is not installed)​

在 Langflow OSS 中，您可以按照错误消息的说明安装缺失的依赖项。

要管理 Langflow Desktop 中的依赖项，请参阅 在 Langflow Desktop 中安装自定义依赖项。

Langflow 升级问题 (Langflow upgrade issues)​

升级 Langflow 版本时可能会出现以下问题。

有关管理 Langflow 版本的信息，请参阅 安装 Langflow。

运行迁移时出错 (Something went wrong running migrations)​

当新版本无法覆盖 Langflow 缓存文件夹中的 langflow-pre.db 时，在 Langflow 升级期间可能会出现以下错误：


_10
> Something went wrong running migrations. Please, run 'langflow migration --fix'

要解决此错误，请通过删除 Langflow 缓存文件夹的内容来清除缓存。 文件路径取决于您的操作系统、安装类型和配置选项。 有关更多信息和默认文件路径，请参阅 内存管理选项。

危险

清除缓存会抹除您的设置。 如果您想保留设置文件，请在清除缓存文件夹之前为这些文件创建备份。

Langflow Desktop 显示正在运行最新版本，但实际上版本落后 (Langflow Desktop says it is running the latest version, but it is actually behind)​

如果您运行的是 Langflow Desktop 1.4.2 或更早版本，当有新版本可用时，UI 可能会错误地报告您使用的是最新版本。

这是因为 UI 中的自动更新功能是在 1.4.2 版本中引入的。 早期版本无法自动检测或应用更新。

要解决此问题，请卸载 Langflow Desktop，然后 下载并安装最新版本的 Langflow Desktop。

升级 Pydantic/FastAPI 依赖项后冻结组件时出现 422 错误 (422 error when freezing components after upgrading Pydantic/FastAPI dependencies)​

如果您在本地升级了 Pydantic 和 FastAPI 依赖项，则在尝试冻结组件时可能会遇到 422 错误。

此错误是由于这些依赖项的较新版本中处理请求体的方式发生了变化而导致的。

如果您遇到此问题，请将您的 Langflow 安装更新到 1.6.5 或更高版本，该版本包含此问题的修复。


_10
uv pip install langflow -U

Langflow 卸载问题 (Langflow uninstall issues)​

卸载 Langflow 时可能会出现以下问题。

在 macOS 上卸载 Langflow Desktop 时未删除点目录 (Dot directory isn't deleted when uninstalling Langflow Desktop on macOS)​

在 macOS 上，卸载 Langflow Desktop 会删除 .app 文件，但不会删除 ~/.langflow 中的文件，其中包括在使用过程中生成的缓存和设置等文件。

如果您重新安装 Langflow Desktop，它将从上次安装的现有数据开始。

要完全删除 Langflow Desktop macOS 安装，您还必须删除 ~/.langflow：


_10
rm -rf .langflow

Langflow MCP 问题​

将 Langflow 用作 MCP 服务器或客户端时可能会出现以下问题。

Claude for Desktop 无法正确使用 MCP 服务器工具 (Claude for Desktop doesn't use MCP server tools correctly)​

如果 Claude for Desktop 无法正确使用您的服务器工具，请尝试在 claude_desktop_config.json 配置文件中显式定义本地 uvx 或 npx 可执行文件的路径：

  1. 要查找您的 uvx 路径，请运行 which uvx。

    要查找您的 npx 路径，请运行 which npx。

  2. 在您的 claude_desktop_config.json 文件中，添加 Langflow MCP 服务器配置的路径，如以下示例所示。


    _11
    {
    _11
    "mcpServers": {
    _11
    "PROJECT_NAME": {
    _11
    "command": "PATH_TO_UVX",
    _11
    "args": [
    _11
    "mcp-proxy",
    _11
    "http://LANGFLOW_SERVER_ADDRESS/api/v1/mcp/project/PROJECT_ID/streamable"
    _11
    ]
    _11
    }
    _11
    }
    _11
    }

在 Windows 上基于浏览器的 MCP 流不打开浏览器 (MCP browser-based flows don't open a browser on Windows)​

这是在 Windows 上将 MCP 工具与浏览器导航操作（如 Playwright）结合使用时的一个已知问题：代理可以成功执行该工具，但浏览器选项卡或窗口不会打开。

此问题发生的原因是 MCP 服务器是从 Python 进程运行的，这会阻止它在 WSL 或 Windows 中打开浏览器窗口。

要解决此问题，请使用 Playwright MCP 仓库 中记录的独立 MCP 服务器方法。 服务器启动并运行后，您可以将其作为 HTTP/SSE 服务器添加到 Langflow 中。

对于其他浏览器导航工具，请参阅提供商的文档以获取特定的故障排除指南。

在混合 Windows/WSL 环境中 MCP 服务器显示“未连接工具或提示” ("No tools or prompts connected" on MCP servers in mixed Windows/WSL environments)​

如果您在使用 Langflow Desktop 作为 MCP 服务器且客户端运行在不同环境（例如 Windows 主机上的 Langflow 和 WSL 中的 MCP 客户端）时遇到“未连接工具或提示”错误或连接失败，这是由于 Windows 和 WSL 环境之间的网络隔离造成的。

WSL 无法直接访问 Windows 的本地主机 (localhost) 服务，且在 Windows 主机上运行的 Langflow 无法通过 localhost:7860 被 WSL 客户端访问。

要解决此问题，请在相同的操作环境中运行服务器和主机。

或者，配置 Langflow Desktop 以通过默认的 Windows IP 地址 10.255.255.254:7860 而不是 localhost 接受来自 WSL 的连接。

嵌入模型组件中的令牌长度限制错误 (Token length limit errors in Embedding Model components)​

如果您的分块策略与嵌入模型的分词限制不一致，可能会发生令牌长度错误。 有关更多信息，请参阅 由于块大小导致的分词错误。

Docker 容器中的文档处理错误 (Document processing errors in Docker containers)​

如果您在 Docker 容器中运行 Langflow，在使用处理文件或图像的组件（例如 读取文件 (Read File) 组件 或 Docling 组件）时可能会遇到错误。要解决这些错误，您可能需要安装额外的系统依赖项。

在基于 Linux 的 Docker 容器中运行 Langflow 时，Docling 需要基础 Docker 镜像中未包含的系统库。如果您看到与文档或图像处理相关的错误，请将以下内容添加到您的 Dockerfile 中：


_10
RUN apt-get update && apt-get install -y libgl1 libglib2.0-0

Docling 执行文档处理操作需要这些依赖项。

有关自定义 Docker 镜像的更多信息，请参阅 使用您自己的代码自定义 Langflow Docker 镜像。

自定义组件和集成问题 (Custom components and integrations issues)​

有关第三方集成的故障排除建议，请参阅 Langflow 文档中有关该集成的信息以及提供商的文档。

如果您正在构建自定义组件，请参阅 自定义 Python 组件的错误处理和日志记录。

自定义组件未出现在可视化编辑器中 (Custom components not appearing in the visual editor)​

如果您的自定义组件未出现在 Langflow 可视化编辑器中，请尝试以下故障排除步骤：

  1. 确保您的组件遵循 所需的目录结构。


    _10
    /your/custom/components/path/ # 由 LANGFLOW_COMPONENTS_PATH 设置的基础目录
    _10
    └── category_name/ # 决定菜单名称的必需类别子文件夹
    _10
    ├── __init__.py # 必需
    _10
    └── custom_component.py # 组件文件

  2. 验证每个类别目录是否包含 __init__.py 文件。 这是 Python 将目录识别为模块所必需的。

  3. 对于 LANGFLOW_COMPONENTS_PATH，请使用命令行参数而不是环境变量。 如果您使用的是 LANGFLOW_COMPONENTS_PATH 环境变量且组件未加载，请尝试使用 --components-path 命令行参数代替：


    _10
    uv run langflow run --components-path /path/to/your/custom/components

如果您继续遇到问题，请在 GitHub 上报告，并提供有关您的目录结构和组件设置的详细信息。

另请参阅 (See also)​

Search