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，即使业务代码没有显式创建它也会出现解析错误。优先级：

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

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

可观测与测试清单

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