跳到主要内容

Langflow 故障排除

本页针对您在使用 Langflow 或为 Langflow 贡献代码时可能遇到的问题提供故障排除建议。

组件缺失​

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

如果组件似乎从 核心组件和菜单中缺失，请尝试以下操作

如果仍无法找到该组件，请参阅 Langflow GitHub Issues 和 Discussions。

游乐场 (Playground) 中没有输入框​

如果 Playground 中没有消息输入字段，请确保您的工作流包含一个 Chat Input 组件，且该组件已直接或间接连接到 Language Model 或 Agent 组件的 Input 端口。

由于 Playground 是为使用 LLM 进行问答格式的工作流（如聊天机器人和智能体）而设计的，因此工作流必须包含 Chat Input、Language Model/Agent 和 Chat Output 组件，才能受到 Playground 聊天界面的完全支持。

有关更多信息，请参阅在 Playground 中测试工作流。

密钥缺失、未找到密钥或 API 密钥无效​

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

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

Langflow 安装问题​

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

Langflow 安装在 pip 依赖解析时卡住​

使用 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 上安装 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 包导致的安装失败​

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

基于 Intel 的 Mac 需要 Protocol buffers (protoc)​

如果您在基于 Intel 的 Mac 上安装 Langflow，如果未安装 Protocol Buffers 编译器 (protoc)，可能会遇到安装错误。

此要求不适用于基于 ARM64 的 Apple Silicon Mac。

要解决此问题，请使用 brew install protobuf 安装 protoc。

有关更多信息（包括其他安装方法），请参阅 Protocol buffers 安装文档。

Windows 上的 Langflow Desktop 需要 C++ 构建工具​

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

Langflow 启动问题​

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

找不到 langflow.__main__ 模块​

当您尝试使用命令 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，但系统中已经安装了之前的版本。在这种情况下，您可能运行了错误的可执行文件。

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

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

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

无法从终端获取环境变量​

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

访问 Langflow Desktop 启动日志​

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

运行多个流时用户未找到或处于非活跃状态​

当在不同端口运行多个本地 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 实例。

包未安装​

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

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

PostgreSQL asyncpg 驱动兼容性问题​

使用 PostgreSQL 数据库初始化 Langflow 时可能会出现以下错误


_10
sqlalchemy.exc.DBAPIError: (sqlalchemy.dialects.postgresql.asyncpg.Error) <class 'asyncpg.exceptions.DataError'>: invalid input for query argument $7: datetime.datetime(2025, 10, 31, 14, 8, 5... (can't subtract offset-naive and offset-aware datetimes)

此错误的发生是因为 asyncpg 的时区处理比 psycopg2 更严格，且与 Langflow 当前的数据库架构不完全兼容。

要解决此问题，请从安装中移除 asyncpg 并改用 psycopg2。

PostgreSQL 版本不匹配：UNIQUE NULLS DISTINCT 语法错误​

使用 PostgreSQL 数据库初始化 Langflow 时可能会出现以下错误


_10
(psycopg.errors.SyntaxError) syntax error at or near "NULLS"
_10
LINE 13: CONSTRAINT file_name_user_id_key UNIQUE NULLS DISTINCT (nam...

当您使用低于 15 版本的 PostgreSQL 时，会发生此错误。这些版本不支持 Langflow 数据库架构中使用的 UNIQUE NULLS DISTINCT 语法。配置为使用 PostgreSQL 时，Langflow 需要 PostgreSQL 15 或更高版本。

要解决此问题，请将您的 PostgreSQL 实例升级到版本 15 或更高，然后重新启动 Langflow。

必须将 API 密钥作为查询参数或请求头传递​

尝试在 Langflow 登录页面注册时可能会出现以下错误：An API key must be passed as query or header。

这意味着 LANGFLOW_AUTO_LOGIN 被设置为 false，且只有超级用户可以创建和激活非超级用户账户。因此，您被锁定在此 Langflow 实例之外。

如果您不是管理员，则超级用户必须在您登录前创建并激活非超级用户账户。

如果您是管理员，请使用超级用户账户登录，或在设置 LANGFLOW_AUTO_LOGIN=true 的情况下重新启动 Langflow。

有关更多信息，请参阅在启用身份验证的情况下启动 Langflow 服务器。

Langflow 升级问题​

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

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

运行迁移时出错​

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


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

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

危险

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

Langflow Desktop 显示正在运行最新版本，但实际上版本落后​

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

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

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

升级 Pydantic/FastAPI 依赖后冻结组件出现 422 错误​

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

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

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


_10
uv pip install langflow -U

Langflow 卸载问题​

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

在 macOS 上卸载 Langflow Desktop 时未删除点目录​

在 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 无法正确使用服务器工具，请尝试在 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 浏览器工作流无法打开浏览器​

这是在 Windows 上使用带有浏览器导航操作（如 Playwright）的 MCP 工具时的已知问题：智能体可以成功执行工具，但浏览器标签页或窗口无法打开。

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

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

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

在混合 Windows/WSL 环境中 MCP 服务器显示“未连接工具或提示词”​

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

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

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

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

升级工作流后 MCP Tools 组件丢失工具模式选项​

如果您升级了在 Tool Mode 下使用 MCP Tools 组件的现有工作流，该组件在升级后可能会丢失其 Tool Mode 设置。这可能会破坏依赖该组件的 Tool Mode 来向智能体公开 MCP 工具的工作流。

如果您在升级 Langflow 1.7.1 或更早版本中创建的工作流时遇到此问题，请执行以下操作：

  1. 在工作流中选择 MCP Tools 组件。

  2. 点击 Code 以打开组件的代码编辑器。

  3. 在组件的模板结构中，找到 inputs 下的 tool_mode 字段。该字段可能缺失或被设置为 false。

  4. 如果 tool_mode 字段缺失，请添加该字段，并将其设置为 true


    _10
    tool_mode = True

  5. 点击 Check & Save 以应用代码更改。

嵌入模型 (Embedding Model) 组件中的 Token 长度限制错误​

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

Docker 容器中的文档处理错误​

如果您在 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 镜像。

自定义组件和集成问题​

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

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

自定义组件未出现在可视化编辑器中​

如果您的自定义组件未出现在 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 上报告，并提供关于目录结构和组件设置的详细信息。

另请参阅​

Search