مرجع R.6

خطاها

Errors

فهرست مطالب
  1. langchain
  2. langchain-core
  3. langgraph
  4. بسته‌های checkpoint و store
  5. سایر بسته‌ها، بر اساس آزمون‌های آزمایشگاهی
  6. هشدارها

هر خطا و هشدار در این راهنما، دارای یک کلاس، یک بسته‌ی صادرکننده و یک شماره خط دقیق است و متن‌های زیر مستقیماً از لاگ‌های ثبت‌شده کپی شده‌اند.

این صفحه راهنمای جستجو بر اساس کلاس خطا است. بخش نشانه، علت و راه‌حل نیز راهنمای جستجو بر اساس نشانه‌های ظاهری خطا به همراه راه‌حل رفع هر پیام است. تک‌تک پیام‌ها از فایل‌های لاگِ رویدادها یا لاگ‌های محیط آزمایشگاهی کپی شده‌اند. مواردی که با عبارت «خارج از لاگ ثبت‌شده» مشخص شده‌اند، مستقیماً از سورس‌کد برداشته شده‌اند. متن‌های داخل علامت‌های کم‌تر/بیش‌تر مانند <seconds>، مقادیر متغیری هستند که ابزار ثبت آن‌ها را ماسک کرده است. پیام‌های طولانی پس از اولین جمله‌شان بریده شده‌اند و خط بریده‌شده در همان نقطه‌ای که لاگ ادامه می‌یابد به پایان می‌رسد.

langchain

کلاس پیام صادرشده در
AssertionError Please remove duplicate middleware instances. {{code libs/langchain_v1/langchain/agents/factory.py:1164}}
ValueError Unable to infer model provider for model='qwen3:4b'. Please specify 'model_provider' directly. {{code libs/langchain_v1/langchain/chat_models/base.py:641}}
StructuredOutputValidationError، خارج از لاگ ثبت‌شده Failed to parse structured output for tool 'Answer': Failed to parse data to Answer: 1 validation error for Answer {{code libs/langchain_v1/langchain/agents/structured_output.py:62-104}}
StructuredOutputValidationError Failed to parse structured output for tool 'Answer': Native structured output expected valid JSON for Answer, but parsing failed {{code libs/langchain_v1/langchain/agents/structured_output.py:426}}
MultipleStructuredOutputsError، به‌صورت متن برای مدل فرستاده می‌شود Error: Model incorrectly returned multiple structured responses (Answer, Refusal) when only one is expected. {{code libs/langchain_v1/langchain/agents/structured_output.py:43-57}}
ValueError Unsupported schema type: <class 'typing._UnionGenericAlias'>. {{code libs/langchain_v1/langchain/agents/structured_output.py:191}}
ModelCallLimitExceededError Model call limits exceeded: run limit (1/1) {{code libs/langchain_v1/langchain/agents/middleware/model_call_limit.py:60-63}}
ToolCallLimitExceededError Tool call limit reached: run limit exceeded (2/1 calls). {{code libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py:97-105}}
ValueError ToolErrorMiddleware requires ، سپس نام‌های دو کنترل‌کننده {{code libs/langchain_v1/langchain/agents/middleware/tool_error.py:112}}
ValueError ProviderToolSearchMiddleware requires a provider with server-side tool search, but got 'ollama'; supported providers: anthropic, openai {{code libs/langchain_v1/langchain/agents/middleware/provider_tool_search.py:146-151}}
PIIDetectionError Detected 1 instance(s) of email in text content {{code libs/langchain_v1/langchain/agents/middleware/_redaction.py:29-42}}
ValueError Number of human decisions (1) does not match number of hanging tool calls (2). {{code libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py:822}}
ValueError MCP target 'server.py' is not a valid URL. {{code libs/langchain_v1/langchain/mcp/adapter.py:108}}
NotImplementedError، به‌صورت پیام خطای ToolMessage پس از Error calling tool 'ask_legacy': برای مدل فرستاده می‌شود This MCP server asked for input over the legacy server-initiated elicitation path, which interrupt-based elicitation cannot answer. {{code libs/langchain_v1/langchain/mcp/elicitation.py:236-242}}

متن تلاش مجدد در ToolStrategy از الگوی Error: {error}\n Please fix your mistakes. استفاده می‌کند {{code libs/langchain_v1/langchain/agents/factory.py:128}}. ایجنت این پیام را در قالب یک ToolMessage برای مدل می‌فرستد و اجرا ادامه می‌یابد.

langchain-core

کلاس پیام صادرشده در
ModelRefusalError، خارج از لاگ ثبت‌شده Model refused to produce the requested output: I can't help with that. {{code libs/core/langchain_core/exceptions.py:137-154}}
ValueError، خارج از لاگ ثبت‌شده No generations found in stream. {{code libs/core/langchain_core/language_models/chat_models.py:276}}
NotImplementedError stream_events(version='v2') is not supported. {{code libs/core/langchain_core/runnables/base.py:1818}}
NotImplementedError، متن خالی هنگام فراخوانی bind_tools روی مدل چت ساختگی پیش‌فرض صادر می‌شود {{code libs/core/langchain_core/language_models/chat_models.py:2409-2426}}

کلاس ModelRefusalError زیرکلاسی از ModelError است {{code libs/core/langchain_core/exceptions.py:73}}. میان‌افزار ModelRefusalMiddleware این خطا را از درون یک بلوک امتناع مدل صادر می‌کند {{code libs/langchain_v1/langchain/agents/middleware/model_refusal.py:27-30}}.

langgraph

کلاس پیام صادرشده در
GraphRecursionError Recursion limit of 10007 reached without hitting a stop condition. You can increase the limit by setting the ، سپس recursion_limit و config key. {{code libs/langgraph/langgraph/pregel/main.py:3119-3126}}
InvalidUpdateError At key 'value': Can receive only one value per step. Use an Annotated key to handle multiple values. {{code libs/langgraph/langgraph/channels/last_value.py:61}}
ValueError Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id {{code libs/langgraph/langgraph/pregel/main.py:2701-2705}}
AttributeError 'SyncPregelLoop' object has no attribute '_put_checkpoint_fut' {{code libs/langgraph/langgraph/pregel/main.py:3105}}
NodeTimeoutError Node 'slow' exceeded its run timeout of 0.050s (elapsed: <seconds>). {{code libs/langgraph/langgraph/errors.py:232-275}}
TypeError stream_events(version='v3') / astream_events(version='v3') do not accept stream_mode; {{code libs/langgraph/langgraph/pregel/main.py:395-400}}
UnknownInterruptError Unknown or already-consumed interrupt: <id> {{code libs/langgraph/langgraph/pregel/_loop.py:1059}}
RuntimeError When there are multiple pending interrupts, you must specify the interrupt id when resuming. {{code libs/langgraph/langgraph/pregel/_loop.py:1068}}
RuntimeError، خارج از لاگ ثبت‌شده Cannot use Command(resume=...) without checkpointer {{code libs/langgraph/langgraph/pregel/_loop.py:1034}}
KeyError 'checkpoint_ns' آزمایشگاه T17-claims-mac
KeyError '__pregel_scratchpad'، از interrupt() بیرون از گراف، مثل ابزار MCP که ورودی درخواست می‌کند {{code libs/langgraph/langgraph/types.py:1030}}
TypeError Tool lookup returned unexpected type: <class 'str'>، برای ابزاری به نام lookup {{code libs/prebuilt/langgraph/prebuilt/tool_node.py:1486}}

سایر کلاس‌های خطای ماژول langgraph.errors عبارت‌اند از: GraphBubbleUp، GraphInterrupt، NodeInterrupt، ParentCommand، EmptyInputError، TaskNotFound، NodeCancelledError و GraphDrained {{code libs/langgraph/langgraph/errors.py:52-210}}. کلاس GraphBubbleUp کلاس پایه‌ی GraphInterrupt، ParentCommand و GraphDrained است. این خطاها جریان کنترل برنامه را جابه‌جا می‌کنند و حلقه‌ی داخلی آن‌ها را مدیریت می‌کند. آن‌ها را فقط زمانی می‌بینید که یک گره را بیرون از ساختار گراف فراخوانی کنید.

بسته‌های checkpoint و store

کلاس پیام صادرشده در
InvalidNamespaceError Invalid namespace label 'bob.x' found in ('users', 'bob.x'). Namespace labels cannot contain periods ('.'). {{code libs/checkpoint/langgraph/store/base/init.py:1333-1334}}
TypeError Type is not msgpack serializable: Plain انکودر ormsgpack، در آزمایشگاه T13-serde-mac
ValueError LANGGRAPH_AES_KEY environment variable is not set. {{code libs/checkpoint/langgraph/checkpoint/serde/encrypted.py:54-56}}

سایر بسته‌ها، بر اساس آزمون‌های آزمایشگاهی

کلاس پیام صادرشده توسط پوشه‌ی آزمایشگاه
MCPError Connection closed mcp، وقتی سرور stdio در حین فراخوانی متوقف می‌شود T12-mcp-mac
MCPError Request 'tools/call' timed out mcp، هنگام اتمام مهلت زمانیِ fastmcp.Client T12-mcp-mac
RemoteProtocolError Server disconnected without sending a response. httpx، وقتی سرور HTTP در حین فراخوانی متوقف می‌شود T12-mcp-mac
MCPError Elicitation not supported mcp، برای کلاینتی بدون کنترل‌کننده‌ی استخراج ورودی روی پروتکل 2026-07-28 T20-mcp-edges-mac
MCPError Tool 'ask_name' returned an InputRequiredResult to request client input, but the multi-round-trip result type (SEP-2322) only exists at MCP 2026-07-28; this connection negotiated '2025-11-25'. سرور FastMCP، روی اتصالی قدیمی T20-mcp-edges-mac
LangSmithConnectionError Connection error caused failure to GET /datasets in LangSmith API. Please confirm your internet connection. langsmith، از طریق پلاگین pytest در صورت فعال بودن ردگیری محاسبات و نبود اتصال اینترنت T19-pytest-plugin-x86
ValueError log_outputs should only be called within a pytest test decorated with @pytest.mark.langsmith, and with tracing enabled (by setting the LANGSMITH_TRACING environment variable to 'true'). langsmith، برای تستی بدون نشانه‌گذاری با وجود فعال بودن ردگیری محاسبات T19-pytest-plugin-x86
ValueError، به‌صورت INTERNALERROR در pytest با کد خروج 3 --langsmith-output not supported when env varLANGSMITH_TEST_TRACKING='false'. Please remove the'--langsmith-output' option or enable test tracking. دو فاصله‌ی جاافتاده در خود کد هستند langsmith، در {{code src/langsmith/pytest_plugin.py:311-317}} T19-pytest-plugin-x86
ValueError log_inputs should only be called within a pytest test decorated with @pytest.mark.langsmith, and with tracing enabled (by setting the LANGSMITH_TRACING environment variable to 'true'). langsmith، برای تست نشانه‌گذاری‌شده با فعال بودن ردیابی و مقداردهی نشدن LANGSMITH_TRACING، در {{code src/langsmith/testing/_internal.py:1166-1168}} T21-langsmith-account-mac
LangSmithConflictError، ناشی از کد وضعیت HTTP 409 Nothing to commit: prompt has not changed since latest commit API ابری، برای push_prompt در صورتی که پرامپت تغییری نکرده باشد T21-langsmith-account-mac
LangSmithNotFoundError، ناشی از کد وضعیت HTTP 404 Commit not found API ابری، برای pull_prompt با تگی که وجود ندارد T21-langsmith-account-mac
LangSmithNotFoundError Project healthy-coast-30 not found langsmith، هنگام خواندن مقدار experiment_name که evaluate(upload_results=False) برگردانده است T21-langsmith-account-mac
خطای CLI، کد خروج 2 Error: Docker not installed or not running langgraph-cli 0.4.43، برای دستور langgraph up وقتی دیمن Docker در حال اجرا نیست، پیش از هرگونه بررسی کلید T21-langsmith-account-mac
HTTP 409 Thread is already running a task. Wait for it to finish or choose a different multitask strategy. langgraph-api 0.18.0، با استراتژی reject T15-agent-server-x86
ValueError License verification failed. Please ensure proper configuration: langgraph-api 0.18.0 ذیل langgraph up T15-agent-server-x86

هشدارها

دسته‌بندی پیام صادرشده در
LangChainBetaWarning نام ماژول langchain.mcp، سپس is in beta. It is actively being worked on, so the API may change. {{code libs/langchain_v1/langchain/mcp/init.py:25-29}}
LangChainBetaWarning The middleware ، سپس ModelRouterMiddleware و is in beta. {{code libs/core/langchain_core/_api/beta_decorator.py:252}}
LangChainBetaWarning The v3 streaming protocol on Pregel is experimental. {{code libs/langgraph/langgraph/pregel/main.py:3617}}
LangGraphDeprecatedSinceV10 نام checkpoint_during، سپس is deprecated and will be removed. Please use، نام durability و instead. {{code libs/langgraph/langgraph/pregel/main.py:2837-2840}}
LangGraphDeprecatedSinceV10 NodeInterrupt is deprecated. Please use ، سپس langgraph.types.interrupt و instead. {{code libs/langgraph/langgraph/errors.py:113-121}}
LangGraphDeprecatedSinceV10 Importing Send from langgraph.constants is deprecated. {{code libs/langgraph/langgraph/constants.py:37}}
LangGraphDeprecatedSinceV11 Accessing GraphOutput via، سپس result[key] و is deprecated. لاگ 24-stream-v2.txt
UserWarning، صادرشده از warnings.warn نام durability، سپس has no effect when no checkpointer is present. {{code libs/langgraph/langgraph/pregel/main.py:2929-2932}}
هشدار ثبت‌شده در لاگ Deserializing unregistered type __main__.Color from checkpoint. This will be blocked in a future version. {{code libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py:600}}
LangSmithBetaWarning پارامتر 'upload_results' parameter is in beta. {{code src/langsmith/evaluation/_runner.py:402}}
LangSmithDeprecationWarning list_runs() is deprecated and will be removed after Jan 31, 2027.، سپس نام فراخوانی جدید {{code src/langsmith/client.py:4219}}
UserWarning Pydantic serializer warnings:، سپس PydanticSerializationUnexpectedValue برای فیلد context pydantic، برای دیکشنری context روی ایجنتی فاقد context_schema

منابع: capture/out/01-init-chat-model.txt، capture/out/04-tool-errors.txt، capture/out/08-structured-errors.txt، capture/out/09-middleware-order.txt، capture/out/11-mw-call-limits.txt، capture/out/13-mw-fallback-refusal.txt، capture/out/14-mw-pii.txt، capture/out/15-mw-hitl-batched.txt، capture/out/18-mw-selection-emulation.txt، capture/out/20-mw-decisions.txt، capture/out/24-stream-v2.txt، capture/out/25-stream-events-v3.txt، libs/core/langchain_core/language_models/fake_chat_models.py در langchain==1.5.0، capture/out/28-checkpoint-memory.txt، capture/out/31-durability.txt، capture/out/33-store.txt، capture/out/34-stategraph-reducers-send-command.txt، capture/out/37-error-handler-timeout.txt، capture/out/38-recursion-limit.txt، capture/out/40-mcp.txt، capture/out/42-langsmith.txt؛ لاگ‌های آزمایشگاهی capture/lab/T06-structured-output-mac/03-ollama-seq-n10.jsonl، capture/lab/T07-approvals-x86/01-cases.jsonl، capture/lab/T08-parallel-tools-mac/02-idless-and-dupnames.jsonl، capture/lab/T12-mcp-mac/01-langchain-mcp.jsonl، capture/lab/T13-serde-mac/03-round-trip.jsonl، capture/lab/T13-serde-mac/04-round-trip-log.txt، capture/lab/T14-stores-mac/01-memory-sqlite.jsonl، capture/lab/T15-agent-server-x86/04-double-texting.jsonl، capture/lab/T15-agent-server-x86/10-up-license-excerpt.txt، capture/lab/T17-claims-mac/02-replay-and-fork.jsonl، capture/lab/T19-pytest-plugin-x86/02-off-noenv-output-rep1-stdout.txt، capture/lab/T19-pytest-plugin-x86/02-on-noenv-refuse-rep1-stdout.txt، capture/lab/T20-mcp-edges-mac/01-mcp-edges.jsonl، capture/lab/T21-langsmith-account-mac/04-e3-on-rep1-stdout.txt، capture/lab/T21-langsmith-account-mac/04-e3-inspect-stdout.txt، capture/lab/T21-langsmith-account-mac/05-e4-hub.json، capture/lab/T21-langsmith-account-mac/06-e2-false.json، capture/lab/T21-langsmith-account-mac/07-e5-up.txt؛ فایل‌های کد ذکرشده در هر ردیف، در langchain==1.5.0، langchain-core 1.8.0، langgraph 1.2.22 و langsmith 0.14.17.

ترجمه‌ی فارسی Errors از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما