بخش 8.6 · بهره‌برداری و نگهداری

نشانه، علت و راهکار رفع خطا

Symptom, cause, fix

فهرست مطالب
  1. نحوه‌ی خواندن جدول‌ها
  2. مدل‌ها و ابزارها
  3. ایجنت‌ها و میان‌افزارها
  4. استریمینگ و حافظه
  5. گراف‌ها، وقفه‌ها و محدودیت‌ها
  6. یکپارچه‌سازی‌ها و سرور
  7. خرابی‌های بدون پیام خطا

هر پیام خطایی در این راهنما، به شرطی که بدانید کدام لایه آن را صادر کرده، علت وقوعش را هم مشخص می‌کند؛ از سوی دیگر، چند مورد از خرابی‌ها هیچ خطایی صادر نمی‌کنند که باید آن‌ها را بر اساس نشانه‌شان جستجو کنید.

ساعت 2 نیمه‌شب فرایند اجرا با پیامی متوقف می‌شود که تا به حال ندیده‌اید. متن پیام به کلاسی از یکی از پنج بسته‌ی نرم‌افزاری اشاره دارد و ردگیری پشته (stack trace) از دل کدهای LangGraph می‌گذرد؛ کدهایی که شما ننوشته‌اید. در این وضعیت، به علت، راهکار رفع خطا و بخشی که موضوع را توضیح داده نیاز دارید.

پس از پایان این بخش، می‌توانید هر پیام خطایی را در تمامی لایه‌های سیستم جستجو کنید، علت و راهکار رفع آن را بیابید و به بخش مربوطه‌اش بروید.

نحوه‌ی خواندن جدول‌ها

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

جدول پایانی به خرابی‌هایی اختصاص دارد که هیچ خطایی صادر نمی‌کنند. نشانه‌ی این خرابی‌ها مواردی مثل دریافت نتیجه‌ی نادرست، خروج کند از برنامه، یا اجرای ابزاری است که نباید اجرا می‌شد.

مدل‌ها و ابزارها

پیام علت راهکار رفع خطا بخش
ValueError: Unable to infer model provider for model='qwen3:4b'. Please specify 'model_provider' directly. رشته‌ی نام مدلی بدون پیشوند ارائه‌دهنده که init_chat_model بتواند آن را استنتاج کند بنویسید ollama:qwen3:4b، یا model_provider را ارسال کنید 3.2
pydantic_core._pydantic_core.ValidationError: 1 validation error for lookup_order ابزاری با پارامتر محیط اجرای ابزار (ToolRuntime) خارج از ایجنت (Agent) فراخوانی شده است آن را از طریق ایجنت فراخوانی کنید، یا تابع زیرین ابزار را تست کنید 3.4
Error: subtract is not a valid tool, try one of [add]. مدل ابزاری را خواسته که ایجنت ندارد نیازی به اقدام نیست. ایجنت این متن را به عنوان یک ToolMessage به مدل پس می‌فرستد 3.4
ValueError: ToolErrorMiddleware requires و سپس نام‌های on_error و aon_error با فونت کد میان‌افزار ToolErrorMiddleware بدون کنترل‌کننده (handler) ساخته شده است مقدار on_error، یا برای ابزارهای ناهمگام aon_error را ارسال کنید 3.4

ایجنت‌ها و میان‌افزارها

پیام علت راهکار رفع خطا بخش
AssertionError: Please remove duplicate middleware instances. دو نمونه از یک کلاس میان‌افزار در لیست وجود دارد یکی را نگه دارید، یا برای کلاس یک name اختصاصی تعریف کنید 4.5
StructuredOutputValidationError: Failed to parse structured output for tool 'Answer': Failed to parse data to Answer: 1 validation error for Answer استفاده از ToolStrategy همراه با handle_errors=False، و پاسخی که با اسکیما مطابقت ندارد handle_errors را روشن بگذارید، یا خطا را داخل کد خودتان مدیریت کنید 4.2
StructuredOutputValidationError: Failed to parse structured output for tool 'Answer': Native structured output expected valid JSON for Answer, but parsing failed استفاده از ProviderStrategy و دریافت پاسخ در قالب متن ساده. این حالت دوباره تلاش نمی‌کند. در Ollama هنگام استفاده از ابزارها، اولین فراخوانی با این خطا روبه‌رو می‌شود در Ollama همراه با ابزارها، response_format را خاموش بگذارید و پس از پایان اجرا یک بار with_structured_output را فراخوانی کنید. روی Claude، استراتژی ProviderStrategy در 39 وظیفه از 39 مورد مقدار را برگرداند 4.2، 4.3
Error: Model incorrectly returned multiple structured responses (Answer, Refusal) when only one is expected. دو فراخوانی ساختاریافته در یک پاسخ مدل، که به خود مدل پس فرستاده شده است نیازی به اقدام نیست. فراخوانی بعدی معمولاً فقط یک پاسخ می‌دهد 4.2
ValueError: Unsupported schema type: <class 'typing._UnionGenericAlias'>. استفاده از ProviderStrategy همراه با اسکیمای Union، که هنگام ساخت ایجنت صادر می‌شود برای تایپ‌های union از ToolStrategy استفاده کنید 4.2
ModelCallLimitExceededError: Model call limits exceeded: run limit (1/1) میان‌افزار ModelCallLimitMiddleware همراه با exit_behavior="error" سقف محدودیت را بالا ببرید، یا با exit_behavior="end" به اجرا پایان دهید 4.6
ToolCallLimitExceededError: Tool call limit reached: run limit exceeded (2/1 calls). میان‌افزار ToolCallLimitMiddleware همراه با exit_behavior="error" سقف محدودیت را بالا ببرید، یا از continue یا end استفاده کنید 4.6
ValueError: ProviderToolSearchMiddleware requires a provider with server-side tool search, but got 'ollama'; supported providers: anthropic, openai مدلی از یک ارائه‌دهنده که جستجوی سمت سرور ابزارها را ندارد از مدلی از Anthropic یا OpenAI استفاده کنید، یا میان‌افزار را بردارید 4.6
ConnectionError: third is down، خارج از لاگ ثبت‌شده میان‌افزار ModelFallbackMiddleware، در حالی که تک‌تک مدل‌های زنجیره با شکست مواجه شده‌اند. اجرا آخرین خطا را صادر می‌کند مدلی از ارائه‌دهنده‌ای دیگر اضافه کنید و خطاهای قبلی را در لاگ بخوانید 4.7
ModelRefusalError: Model refused to produce the requested output: I can't help with that.، خارج از لاگ ثبت‌شده بلوک امتناع مدل (refusal)، در حالی که ModelRefusalMiddleware روی بالا آوردن خطا تنظیم شده است درخواست را تغییر دهید، یا بگذارید میان‌افزار به سراغ مدل پشتیبان برود 4.7
PIIDetectionError: Detected 1 instance(s) of email in text content میان‌افزار PIIMiddleware با استراتژی block زمانی که اجرا باید ادامه یابد، از پاک‌سازی داده‌های حساس (redact)، mask یا hash استفاده کنید 4.8

استریمینگ و حافظه

پیام علت راهکار رفع خطا بخش
TypeError: stream_events(version='v3') / astream_events(version='v3') do not accept stream_mode; ارسال stream_mode به نسخه v3، در حالی که خودش حالت‌هایش را می‌سازد پارامتر stream_mode را حذف کنید و تصویرهای (projections) استریم v3 را بخوانید 5.1
NotImplementedError: stream_events(version='v2') is not supported. فراخوانی همگام stream_events با نسخه‌ی v2 برای نسخه‌های v1 و v2 از astream_events استفاده کنید، یا به سراغ v3 بروید 5.1
ValueError: No generations found in stream.، خارج از لاگ ثبت‌شده مدل گفت‌وگوی ساختگیِ پیش‌فرض ذیل create_agent همراه با استریمینگ (streaming) با یک مدل واقعی تست کنید، یا با مدلی ساختگی که bind_tools را پیاده‌سازی کرده و فراخوانی ابزار را استریم می‌کند {{code libs/core/langchain_core/language_models/fake_chat_models.py}} 5.1
ValueError: Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id اجرا روی گرافی با چک‌پوینتر (checkpointer) بدون ارسال thread_id مقدار {"configurable": {"thread_id": ...}} را ارسال کنید 5.2
AttributeError: 'SyncPregelLoop' object has no attribute '_put_checkpoint_fut' تنظیم durability="sync" روی گرافی بدون چک‌پوینتر، ایشوی 9267# یک چک‌پوینتر اضافه کنید، یا durability را روی حالت پیش‌فرض بگذارید 5.3
InvalidNamespaceError: Invalid namespace label 'bob.x' found in ('users', 'bob.x'). Namespace labels cannot contain periods ('.'). برچسب فضای نام در مخزن دارای نقطه است پیش از آنکه شناسه به برچسب تبدیل شود، وجود نقطه را رد یا آن را جایگزین کنید 5.4
TypeError: Type is not msgpack serializable: Plain وجود نمونه‌ای از یک کلاس معمولی در وضعیت (state) از dataclass، مدل Pydantic یا dict استفاده کنید 5.6
Deserializing unregistered type __main__.Color from checkpoint. This will be blocked in a future version. ذخیره‌ی enum یا کلاس اختصاصی شما در چک‌پوینت بدون مدخل در allowed_msgpack_modules ماژول و کلاس را در allowed_msgpack_modules فهرست کنید 5.6

گراف‌ها، وقفه‌ها و محدودیت‌ها

پیام علت راهکار رفع خطا بخش
InvalidUpdateError: At key 'value': Can receive only one value per step. Use an Annotated key to handle multiple values. دو گره در یک گام روی یک کلید نوشتند و کلید فاقد کاهنده (reducer) است. با وجود چک‌پوینتر، هر دو مقدار ذخیره می‌شوند؛ بنابراین get_state، invoke(None) و تمام نوبت‌های بعدی گفت‌وگو روی آن ترد همین خطا را صادر می‌کنند، ایشوی 9712# با استفاده از Annotated به کلید یک کاهنده بدهید و کد را دیپلوی کنید، سپس کار را با invoke(None) از سر بگیرید. ترد از روی مقادیر ذخیره‌شده کار را تمام می‌کند و هیچ گرهی دوباره اجرا نمی‌شود. متد update_state نیز ترد را خواندنی می‌کند، اما گراف قدیمی در اجرای بعدی دوباره خطا می‌دهد 6.1، 2.2
UnknownInterruptError: Unknown or already-consumed interrupt: <id> فعال بودن حالت سرگیری سخت‌گیرانه با کلید داخلی __pregel_strict_resume، و ارسال دومین پاسخ به یک وقفه (interrupt) وقفه‌های معلق را با get_state بخوانید و به همان‌ها پاسخ دهید 6.4
RuntimeError: When there are multiple pending interrupts, you must specify the interrupt id when resuming. ارسال یک مقدار ساده برای ادامه‌ی کار در حالی که دو وقفه منتظر پاسخ‌اند فرایند را با نگاشتی از شناسه‌ی هر وقفه به پاسخ مربوط به آن ادامه دهید 6.5
ValueError: Number of human decisions (1) does not match number of hanging tool calls (2). بازبینی دسته‌ای (batch)، و کمتر بودن تعداد تصمیم‌ها نسبت به فراخوانی‌های ابزار برای هر فراخوانی، یک تصمیم به ترتیب ارسال کنید 6.5
KeyError: 'checkpoint_ns' متد update_state با کانفیگی که فقط شامل thread_id و checkpoint_id است کانفیگ کامل یک اسنپ‌شات وضعیت (StateSnapshot) از تاریخچه را بفرستید 6.6
NodeTimeoutError: Node 'slow' exceeded its run timeout of 0.050s (elapsed: <seconds>). گره ناهمگامی که اجرای آن بیشتر از timeout طول کشیده است مهلت زمانی را افزایش دهید، یا خطا را با یک error_handler مدیریت کنید 6.8
GraphRecursionError: Recursion limit of 10007 reached without hitting a stop condition. حلقه‌ای بدون خروج، یا اجرایی که به مراحلی بیش از سقف تعیین‌شده نیاز دارد شرط خروج را اصلاح کنید، یا پارامتر recursion_limit را بفرستید 6.8

یکپارچه‌سازی‌ها و سرور

پیام علت راهکار رفع خطا بخش
ValueError: MCP target 'server.py' is not a valid URL. رشته‌ی هدفی که URL از نوع http یا https نیست برای سرور stdio از Path('server.py') استفاده کنید 7.3
MCPError: Connection closed سرور stdio در میانه‌ی فراخوانی خارج شد و اجرا با خطا مواجه شد اجرا را تنها در صورتی تکرار کنید که ابزار بی‌اثر در تکرار (idempotent) باشد؛ در غیر این صورت ابتدا نتیجه‌ی بیرونی را بررسی کنید. فراخوانی بعدی دوباره سرور را راه می‌اندازد 7.3
RemoteProtocolError: Server disconnected without sending a response. سرور HTTP در میانه‌ی فراخوانی قطع شد سرور را ری‌استارت کنید و تنها در صورتی اجرا را تکرار کنید که ابزار بی‌اثر در تکرار باشد. در غیر این صورت ابتدا نتیجه‌ی بیرونی را بررسی کنید 7.3
MCPError: Request 'tools/call' timed out مهلت زمانی تعیین‌شده در fastmcp.Client از مدت اجرای ابزار کوتاه‌تر است مهلت زمانی کلاینت را افزایش دهید. تطبیق‌دهنده (adapter) خودش مهلت زمانی مستقلی ندارد 7.3
Thread is already running a task. Wait for it to finish or choose a different multitask strategy. استفاده از Agent Server با استراتژی reject، و اجرای دوم روی تردی که مشغول است. وضعیت HTTP 409 است بعداً دوباره تلاش کنید، یا اجرا را با enqueue بسازید 8.1
ValueError: License verification failed. Please ensure proper configuration: اجرای langgraph up بدون هیچ‌یک از متغیرهای LANGSMITH_API_KEY یا LANGGRAPH_CLOUD_LICENSE_KEY یکی از این دو را مقداردهی کنید، یا از langgraph dev استفاده کنید 8.1

خرابی‌های بدون پیام خطا

نشانه علت راهکار رفع خطا بخش
ابزاری که بازبین تأیید نکرده بود، پس از یک ویرایش یا پرش اجرا شد بازبینی دسته‌ای، جایی که یک ویرایش می‌تواند ابزارها را جابه‌جا کند و پرش میان‌افزار می‌تواند بازبینی را دور بزند حالت وقفه را با interrupt_mode="per_call" تنظیم کنید 6.5
اجرای دوباره‌ی یک اثر جانبی پس از کرش و ادامه‌ی کار کرش بعد از اجرای ابزار و قبل از ذخیره‌ی تغییرات یا چک‌پوینت رخ داده است. حالت durability="sync" وظیفه‌ای را که تازه برگردانده شده پوشش نمی‌دهد اثر جانبی را بر اساس معنای آن کلیدگذاری کنید (مانند شناسه‌ی ترد و شناسه‌ی سفارش)، و ابتدا سوابق خود را چک کنید. مقادیر tool_call_id و checkpoint_ns تنها در حالت‌های sync و async به عنوان کلید عمل می‌کنند 5.3، 2.3
دو بار شارژ شدن یک درخواست بدون هیچ کرشی، یا دو بار شارژ اضافه بعد از ادامه‌ی کار کلیددار مدل در یک پاسخ واحد، اجرای همان ابزار را دو بار خواسته است پیش از کسر هزینه، سفارش را در سوابق خود بررسی کنید؛ چون کلید tool_call_id اجازه‌ی عبور فراخوانی دوم را می‌دهد 5.3
هشدار بی‌اثر بودن durability زمانی که هیچ چک‌پوینتری در کار نیست انتخاب حالت پایداری روی گرافی که چک‌پوینتر ندارد یک چک‌پوینتر اضافه کنید، یا این آرگومان را بردارید 5.3
هشدار PydanticSerializationUnexpectedValue برای فیلد context دیکشنری context روی ایجنتی که فاقد context_schema است برای ایجنت یک context_schema تعریف کنید 5.4
تغییر یافتن یک مجموعه‌ از تاپل‌ها یا یک منطقه‌ی زمانی پس از بازگشت از چک‌پوینت انواع داده‌ای که سریالایزر بازگشت‌پذیری (round-trip) آن‌ها را بازسازی نمی‌کند لیست‌ها، دیکشنری‌ها و زمان‌های UTC را همراه با نام منطقه‌ی زمانی ذخیره کنید 5.6
بازگرداندن فضاهای نام همه‌ی کاربران توسط list_namespaces پیشوندی که از شناسه‌ی کاربری * ساخته شده است استفاده از * را در شناسه‌ی کاربر رد کنید 5.4
برنامه‌ریزی نکردن دیپ ایجنت با write_todos در Deep Agents 0.7 میان‌افزار TodoListMiddleware گنجانده نشده است میان‌افزار TodoListMiddleware() را در middleware ارسال کنید 7.4
معلق ماندن یا خارج نشدن اسکریپتی که ردگیری محاسبات (tracing) آن روشن است اندپوینت LangSmith قطع است یا خطا می‌دهد و فرایند خروج منتظر ثبت ردگیری‌ها می‌ماند تابع wait_for_all_tracers() را فراخوانی کنید و برای جاب مهلت زمانی بگذارید 7.6
رسیدن اجراهای ایجنت به LangSmith درون tracing_context(enabled="local") کدهای LangChain مقدار "local" را به عنوان روشن در نظر می‌گیرند در کدهای LangChain از tracing_context(enabled=False) استفاده کنید 7.6
در انتظار ماندن مجدد همان تأییدیه پس از کرش ورکر، با وجود ثبت ردیف بازپرداخت نگاشت ادامه‌ی کار در کانفیگ اجرا باقی می‌ماند، بنابراین کرش داخل وظیفه‌ی tools باعث از دست رفتن تصمیم می‌شود ابزار را بر اساس داده‌های ذخیره‌شده در چک‌پوینت کلیدگذاری کنید تا تأیید دوم به صورت بازپخش (replay) انجام شود 9.3
پاسخ مدل به مشتری مبنی بر نبود سفارش، پس از پایان مهلت جستجو (lookup) مدل از متن خطای ابزار پیروی نکرده است پاسخ سیستم به هر خطا را در ارزیابی‌های خود بسنجید و مدلی را انتخاب کنید که این تست‌ها را پاس کند 9.5
دریافت خطای ReadTimeout توسط کلاینت‌های یک سرویس شلوغ، با وجود ادامه‌ی اجراها در حین انتظار اجرا برای سرور مدل، هیچ بایتی از طریق استریم ارسال نشده است پس از قطع استریم، وضعیت ترد را بخوانید و ظرفیت مدل را افزایش دهید 9.7
خواندن فایل .env یا حذف فایل دات‌دار توسط ایجنت، با وجود قانون deny برای /** کتابخانه‌ی Deep Agents الگوهای قوانین را بدون فعال کردن DOTGLOB به wcmatch می‌دهد، بنابراین * و ** نام‌هایی را که با نقطه شروع می‌شوند نادیده می‌گیرند ابتدا دسترسی به /**/.* و /**/.*/** را رد (deny) کنید، و علاوه بر /workspace/**، خود /workspace را نیز مجاز کنید 8.4
افشای فایل‌های یک کاربر دیگر برای کاربر یک دیپ ایجنت استفاده از کارخانه‌ی فضای نام ثابت، مانند ("memories",)، در StoreBackend فضای نام را از روی شناسه‌ی کاربر در کانتکست اجرا بسازید 5.4
اعلام ارسال ایمیل توسط مدل، در حالی که هیچ ایمیلی ارسال نشده است پیامی روی یک تأییدیه‌ی معلق تایپ شده، که رابط Agent Chat UI آن را با یک نتیجه‌ی ابزار صوری می‌بندد امنیت ابزار را به صورت مستقل تأمین کنید و در زمان انتظار برای تأیید، ورودی را غیرفعال کنید 8.2
طول کشیدن 20 اجرای پس‌زمینه‌ی یک گراف 2 ثانیه‌ایِ بدون مدل به مدت 41.0 ثانیه پردازش یک وظیفه در هر ورکر، که رفتار پیش‌فرض langgraph dev است آن را با آرگومان --n-jobs-per-worker 10 اجرا کنید، که در همان تست 5.1 ثانیه زمان برد 8.1

منابع: capture/out/01-init-chat-model.txt، capture/out/03-tools.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/18-mw-selection-emulation.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/lab/internals/02-channels/trace.txt، capture/lab/internals/02-channels/repair.txt، capture/lab/T02-crash-resume-x86/10-summary.txt، capture/lab/failure-drill-x86/drill-run1.log، capture/out/37-error-handler-timeout.txt، capture/out/38-recursion-limit.txt، capture/out/40-mcp.txt؛ capture/lab/summary/structured-output-mac.json، capture/lab/T06-structured-output-mac/03-ollama-seq-n10.jsonl، capture/lab/T14-stores-mac/01-memory-sqlite.jsonl، capture/lab/T13-serde-mac/03-round-trip.jsonl، capture/lab/T13-serde-mac/04-round-trip-log.txt، capture/lab/summary/approvals-x86.json، capture/lab/T17-claims-mac/02-replay-and-fork.jsonl، capture/lab/summary/mcp-mac.json، capture/lab/T15-agent-server-x86/04-double-texting.jsonl، capture/lab/T15-agent-server-x86/10-up-license-excerpt.txt، capture/lab/summary/tracing-mac-real.json، capture/lab/summary/agent-server-x86.json؛ بخش‌های لینک‌شده در هر ردیف؛ capture/lab/chat-ui-mac/summary/extracts.json، capture/lab/summary/permissions-mac.json، capture/lab/summary/store-namespace-mac.json.

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