---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - python
  - errors
  - troubleshooting
topic: LangChain Python 错误分类与生产排障
sources:
  - https://docs.langchain.com/oss/python/langchain/errors/INVALID_PROMPT_INPUT
  - https://docs.langchain.com/oss/python/langchain/errors/INVALID_TOOL_RESULTS
  - https://docs.langchain.com/oss/python/langchain/errors/MESSAGE_COERCION_FAILURE
  - https://docs.langchain.com/oss/python/langchain/errors/MODEL_AUTHENTICATION
  - https://docs.langchain.com/oss/python/langchain/errors/MODEL_NOT_FOUND
  - https://docs.langchain.com/oss/python/langchain/errors/MODEL_RATE_LIMIT
  - https://docs.langchain.com/oss/python/langchain/errors/OUTPUT_PARSING_FAILURE
last_verified: 2026-08-11
---

# LangChain 错误分类与排障

## 先按层定位

| 错误 | 所在层 | 第一检查点 | 是否适合自动重试 |
|---|---|---|---|
| `INVALID_PROMPT_INPUT` | Prompt 构造 | 模板变量、括号转义、MessagesPlaceholder 输入 | 否，先修代码/数据 |
| `MESSAGE_COERCION_FAILURE` | 消息协议 | role/content、消息类、tuple/string 转换 | 否 |
| `INVALID_TOOL_RESULTS` | Tool-call 消息链 | tool call 与 ToolMessage 的一一对应及 ID | 否 |
| `MODEL_AUTHENTICATION` | Provider 认证 | 凭据、环境加载、代理/自定义 endpoint 的认证方式 | 否；轮换或修配置 |
| `MODEL_NOT_FOUND` | Provider 路由 | 模型标识、账户权限、代理允许列表 | 否 |
| `MODEL_RATE_LIMIT` | Provider 容量 | 429/限额、并发、缓存命中、队列 | 是，但必须退避和限次 |
| `OUTPUT_PARSING_FAILURE` | 输出契约 | 原始模型输出、parser 预期、结构化输出能力 | 仅在有修正策略时 |

几个页面标注“当前只用于 langchainjs”，却位于 Python 路由并包含 Python 示例。这意味着错误分类知识可复用，但不能据此断言当前 Python SDK 一定抛出同名错误码；Python 生产代码应以实际异常类型、Provider 状态码和安装版本为准。

## Prompt 与消息输入

### `INVALID_PROMPT_INPUT`

- f-string 模板中的字面量单花括号写成双花括号；需要输出双花括号时继续成倍转义。
- `MessagesPlaceholder` 必须收到消息数组或 message-like 对象；tuple 简写的占位变量应写成 `{messages}` 形式。
- Prompt Hub 拉取的 prompt 要单独用固定样本测试，避免远端版本变化直接进入生产。
- 排障时记录变量名、类型、长度和模板版本，不记录完整用户输入或秘密。

### `MESSAGE_COERCION_FAILURE`

LangChain 接受消息类/消息模板、`(role, content)` tuple、OpenAI 风格 `{role, content}` 对象与纯字符串；纯字符串会变为 HumanMessage。错误通常来自缺少 `role`/`content`、把类名当 role、JSON 往返后字段丢失，或中间件意外把消息对象字符串化。

边界校验应放在进入模型前：验证数组元素类型、role 枚举、content block 结构与 tool call 字段，错误日志只输出结构摘要。

## Tool-call 配对不变量

`AIMessage.tool_calls` 后必须为每个 tool call 提供且仅提供一个 `ToolMessage`，并精确匹配 `tool_call_id`：

- 少一条：模型看到未完成调用；
- 同一 ID 多条：结果歧义；
- ID 不存在或没有前置 tool call：孤儿结果；
- 并发工具结束顺序可以变化，但关联 ID 不能变化。

持久化/恢复时应原子保存 AI tool calls 与完成结果，或显式保留“待完成”状态；不能只截取部分消息历史再提交给模型。

## Provider 认证、模型与容量

### Authentication

检查凭据值是否有效、环境变量名是否正确且确实加载、dotenv/容器 secret 是否覆盖，以及代理或兼容 endpoint 是否采用不同认证协议。临时把凭据显式传给构造器只能用于隔离“环境加载”问题；不能把密钥写入源码、Notebook、Trace 或异常信息。

### Model not found

同时核对模型字符串、区域/账户是否有权使用、API 版本和兼容代理的模型映射/allowlist。不要把所有 404 都当拼写错误；代理网关可能有自己的别名与权限策略。

### Rate limit

生产处理顺序是入口限流与并发上限 → 请求队列 → 带 jitter 的指数退避 → 对确定性/重复请求缓存 → 配额监控与扩容。多 Provider fallback 只有在输出契约、数据驻留、成本和安全策略一致时才可启用；不得借 fallback 绕过租户限额。

## 输出解析失败

旧 Agent/Chain 可能在内部使用 parser，即使业务代码没有显式创建它也会出现解析错误。优先级：

1. Provider 原生 structured output 或 tool calling；
2. 明确 schema、校验约束与可修复错误反馈；
3. 更精确格式说明；
4. 必要时使用能力更强的模型。

重试应把脱敏后的校验错误反馈给模型，并设置最大次数。持续失败转人工或降级成非结构化结果；不能无限重试，也不能用正则静默“修复”关键业务字段。

## 可观测与测试清单

- Trace 记录 error code、Provider、模型别名、模板/Schema 版本、tool call ID 摘要、attempt 和 latency。
- 认证信息、原始 token、完整 prompt、PII 和工具结果按字段脱敏。
- 单测覆盖 prompt 变量缺失、消息反序列化、tool call 少/多/错 ID、parser 非法输出。
- 集成测试覆盖真实 Provider 认证、无权限模型、限流与 retry-after；不要在单测里伪称已验证线上配额。