خطا و اشکال‌زدایی در n8n

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

بعد از این درس می‌توانی

  • برای هر گره بین Stop Workflow، Continue و Continue (using error output) با دلیل انتخاب کند.
  • Retry On Fail را فقط برای خطاهای قابل تکرار به کار ببرد و محدودیتش را در برابر سیاست کامل تلاش دوباره بداند.
  • یک ورک‌فلوی خطا با Error Trigger بسازد که هشدار قابل اقدام بدون داده حساس بفرستد.
  • اجرای ناموفق را از فهرست اجراها پیدا کند و با بارگذاری داده آن در ویرایشگر یا داده سنجاق‌شده، علت را بازتولید و اصلاح کند.

چرا این درس مهم است

ورک‌فلوی گزارش روزانه برگ سبز سه هفته کار نکرده بود و هیچ‌کس نفهمید. کلید سامانه سفارش چرخانده شده بود، هر صبح گره اول 401 می‌گرفت، اجرا قرمز می‌شد و در فهرست اجراها می‌ماند. کسی هر روز آن فهرست را نگاه نمی‌کرد. ورک‌فلوی دیگری روی همه گره‌ها «Continue» گذاشته بود تا «هیچ‌وقت نایستد»؛ وقتی سامانه تیکت از دسترس خارج شد، ورک‌فلو با داده ناقص ادامه داد و به مشتریان پیام «تیکت شما با شماره undefined ثبت شد» فرستاد.

طرح خطای دوره پایه و سیاست تلاش دوباره دوره HTTP، اینجا به تنظیم واقعی تبدیل می‌شوند: هر گره رفتار خطای مشخص، تلاش دوباره فقط جای درست، و یک ورک‌فلوی خطا که هیچ شکستی را بی‌صدا نگذارد.

مفاهیم کلیدی

یادآوری: خطای قابل تکرار و غیرقابل تکرار، فاصله افزایشی و «هیچ خطایی بی‌صدا نیست» را در دوره پایه و درس چهارم دوره HTTP دیدی.

  • Retry On Fail (تلاش دوباره هنگام شکست): تنظیم گره که پس از شکست، آن را دوباره اجرا می‌کند.
  • Error Output (خروجی خطا): شاخه جدای گره که آیتم‌های شکست‌خورده را با جزئیات خطا به گره بعد می‌دهد.
  • Error Workflow (ورک‌فلوی خطا): ورک‌فلوی جدا که با Error Trigger شروع می‌شود و وقتی اجرای ورک‌فلوی دیگری شکست بخورد، اجرا می‌شود.
  • Stop And Error (گره توقف با خطا): گرهی که اجرا را عمداً با خطا متوقف می‌کند تا ورک‌فلوی خطا فعال شود.
  • Alert (هشدار): پیامی به مسئول که می‌گوید چه چیزی، کجا و کی شکست خورد و قدم بعد چیست.

مدل ذهنی

ورک‌فلو را مثل آشپزخانه رستوران ببین. اگر یک ظرف سوخت، سه راه داری: کل سفارش را متوقف کنی (Stop Workflow)، ظرف را کنار بگذاری و بقیه را سرو کنی و ظرف سوخته را به میز «بازبینی» بفرستی (خروجی خطا)، یا وانمود کنی چیزی نشده و ظرف قبلی را دوباره سرو کنی (Continue). و سرآشپز (ورک‌فلوی خطا) باید هر بار که سفارشی متوقف شد، خبردار شود.

تصمیم رفتار خطا برای یک گره: اگر خطا گذراست مثل 503 یا 429، Retry On Fail با فاصله؛ اگر یک آیتم ایراد دارد و بقیه می‌توانند ادامه دهند، خروجی خطا به صف بررسی؛ اگر خطا کل اجرا را بی‌معنی می‌کند مثل 401، توقف ورک‌فلو؛ هر توقف ورک‌فلوی خطا را با Error Trigger اجرا می‌کند که به مسئول هشدار می‌دهد.

تصمیم رفتار خطا برای یک گره

این تشبیه کجا غلط است؟ در آشپزخانه، ظرف سوخته را همه می‌بینند. در n8n، اجرای ناموفق فقط در فهرست اجراها ثبت می‌شود؛ اگر ورک‌فلوی خطا نسازی، هیچ‌کس خبردار نمی‌شود. و گزینه «Continue» از «وانمود کردن» هم بدتر است: با آخرین داده معتبر ادامه می‌دهدsrc-n8n-node-settings، یعنی ممکن است داده آیتم دیگری را جای این بگذارد.

گام‌به‌گام

گام ۱: رفتار خطای هر گره

در تب Settings هر گره، گزینه On Error سه حالت داردsrc-n8n-node-settings:

حالترفتارکی
Stop Workflowکل اجرا متوقف می‌شود؛ گره‌های بعدی اجرا نمی‌شوندپیش‌فرض امن؛ وقتی ادامه بی‌معنی است (کلید نامعتبر، داده پایه نیامد)
Continueبه گره بعد می‌رود و آخرین داده معتبر را به کار می‌بردتقریباً هرگز برای اقدام بیرونی؛ فقط وقتی شکست این گره هیچ اثری بر بعدی‌ها ندارد
Continue (using error output)جزئیات خطا را به یک شاخه جدا می‌دهد تا مدیریتش کنیوقتی یک آیتم شکست می‌خورد ولی بقیه باید ادامه دهند

قاعده: پیش‌فرض Stop Workflow است؛ هر انحراف از آن دلیل مکتوب می‌خواهد.

گام ۲: Retry On Fail، جای درست

Retry On Fail گره را پس از شکست دوباره اجرا می‌کندsrc-n8n-node-settings؛ معمولاً با تعداد تلاش و فاصله ثابت بین تلاش‌ها. این برای خطای گذرا (503، قطعی شبکه، 429 گاه‌به‌گاه) کافی است. ولی با سیاست کامل درس چهارم دوره HTTP فاصله دارد:

  • همه خطاها را تکرار می‌کند، حتی 401 و 400. برای گره‌هایی که بیشتر خطای ورودی می‌گیرند، روشن نکن.
  • فاصله افزایشی و رعایت Retry-After را خودش انجام نمی‌دهد. برای API با سقف نرخ جدی، دسته‌بندی (درس قبل) مهم‌تر است.
  • برای POST بدون کلید ایدمپوتنسی، تکرار ممکن است رکورد تکراری بسازد.

گام ۳: ورک‌فلوی خطا

یک ورک‌فلوی جدا بساز که با Error Trigger شروع شود و در تنظیمات ورک‌فلوهای اصلی، آن را به‌عنوان Error workflow انتخاب کن؛ یک ورک‌فلوی خطا می‌تواند برای چند ورک‌فلو کار کندsrc-n8n-error-handling. Error Trigger داده‌هایی مثل شناسه و نشانی اجرا، پیام خطا، آخرین گره اجراشده، نام ورک‌فلو و در صورت تلاش دوباره، شناسه اجرای اصلی را می‌گیردsrc-n8n-error-handling.

هشدار خوب چهار چیز دارد و یک چیز ندارد:

  • دارد: نام ورک‌فلو، گره شکست‌خورده، پیام خطای کوتاه، پیوند اجرا.
  • ندارد: داده آیتم‌ها (پیام مشتری، تلفن، بدنه پاسخ)؛ پیوند اجرا برای دیدن جزئیات کافی است و دسترسی به آن کنترل‌شده است.

و یک چیز دیگر: نوع خطا را در هشدار تفکیک کن. «کلید نامعتبر در گزارش روزانه» فوری است؛ «یک تیکت با متن خالی» می‌تواند در گزارش روزانه بیاید.

گام ۴: شکست عمدی با Stop And Error

گاهی هیچ گرهی خطا نمی‌دهد ولی نتیجه غلط است: API صفر سفارش برگرداند در حالی که امروز روز کاری است. با یک If و گره Stop And Error اجرا را عمداً شکست بده تا ورک‌فلوی خطا خبر بدهدsrc-n8n-error-handling. این همان «هیچ خطایی بی‌صدا نیست» برای خطاهای منطقی است.

گام ۵: اشکال‌زدایی با داده همان اجرا

در فهرست اجراهای ورک‌فلو، اجرای ناموفق را باز کن و ببین کدام گره، با کدام ورودی، چه خطایی داده است. گزینه Debug in editor داده آن اجرا را به ویرایشگر می‌آورد و روی گره اول سنجاق می‌کند تا همان شرایط را بازتولید کنی؛ این امکان در Cloud و در اجرای شخصی Community ثبت‌شده (و نسخه‌های پولی) در دسترس استsrc-n8n-debug-executions. اگر نسخه‌ات آن را ندارد، ورودی گره شکست‌خورده را از پنل اجرا بردار و دستی روی گره سنجاق کن.

مثال‌ها

پیاده‌سازی عملی

خطاسازی عمدی و ورک‌فلوی خطا. حدود ۲۲ دقیقه.

اجرای محلی
  1. API آزمایشی (shared/barg-sabz-mock-api.py) را با --host 0.0.0.0 اجرا کن.
  2. ورک‌فلوی «Error Handler»: Error Trigger ← Edit Fields که پیام هشدار را از نام ورک‌فلو، آخرین گره، پیام خطا و نشانی اجرا بسازد ← یک گره خروجی (برای تمرین، POST /tickets با دسته other به‌عنوان «صندوق هشدار»، یا هر کانالی که داری).
  3. ورک‌فلوی آزمایشی با سه گره HTTP Request: GET /flaky، GET /orders/BS-1001 با Credential غلط، و POST /tickets با بدنه بدون text. در تنظیمات آن، Error workflow را «Error Handler» بگذار.
  4. گره /flaky: Retry On Fail روشن؛ اجرا کن و ببین پس از تلاش‌ها موفق می‌شود.
  5. گره با کلید غلط: Stop Workflow؛ اجرا کن؛ هشدار باید برسد.
  6. گره POST /tickets: Continue (using error output) و شاخه خطا به یک Edit Fields «صف بررسی». چند آیتم بفرست که یکی‌شان text ندارد.
  7. اجرای ناموفق را در فهرست اجراها باز کن و اگر نسخه‌ات دارد، Debug in editor را امتحان کن.
  8. پنج مورد assets/failure-cases.md را جواب بده.
سرویس میزبانی‌شده (در دسترس قانونی)

در n8n Cloud (اگر در دسترس قانونی است) به‌جای API محلی، خطا را با Stop And Error یا یک HTTP Request به نشانی نامعتبر بساز. ورک‌فلوی خطا و Debug in editor مثل مسیر محلی است.

بدون اجرا / شبیه‌ساز

پنج مورد assets/failure-cases.md را جواب بده و ورک‌فلوی خطای برگ سبز را روی کاغذ طراحی کن: گره‌ها، متن هشدار نمونه، و اینکه کدام خطاها فوری‌اند.

اشتباه‌های رایج

اشتباهنتیجهکار درست
ورک‌فلوی خطا نساختنشکست‌ها هفته‌ها دیده نمی‌شوندError Trigger و هشدار
Continue روی گره‌های اقدامپیام یا ثبت با داده غلطStop یا خروجی خطا
Retry On Fail روی همه گره‌ها400 و 401 بی‌فایده تکرار می‌شوندفقط خطای گذرا
داده آیتم در متن هشدارپیام مشتری در کانال هشدارنام ورک‌فلو، گره، خطا، پیوند
نیازمودن ورک‌فلوی خطاامنیت کاذبآزمون با Stop And Error
نادیده‌گرفتن خطای منطقی (صفر سفارش)گزارش خالی بی‌صداIf + Stop And Error

اشکال‌زدایی

ورک‌فلو شکست خورده ولی هیچ هشداری نرسیده است.

Error workflow در تنظیمات این ورک‌فلو انتخاب نشده، یا خود ورک‌فلوی خطا شکست خورده است.

تنظیمات ورک‌فلو را ببین؛ فهرست اجراهای ورک‌فلوی خطا را هم ببین.

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

پیام‌های ارسالی گاهی «undefined» یا داده مشتری دیگر دارند.

گرهی پیش از آن On Error روی Continue دارد و با آخرین داده معتبر ادامه داده است.

در اجرا، گره‌هایی را پیدا کن که خطا داده‌اند ولی اجرا ادامه یافته است.

Stop Workflow یا خروجی خطا با مسیر جدا.

گره با Retry On Fail هنوز گاهی شکست می‌خورد و تیکت‌های تکراری هم دیده می‌شود.

خطا 429 یا timeout است؛ فاصله ثابت کافی نیست و POST بدون کلید ایدمپوتنسی تکرار شده است.

پیام خطا و زمان تلاش‌ها را در اجرا ببین؛ تیکت‌های تکراری را با زمان مقایسه کن.

دسته‌بندی و فاصله بیشتر؛ هدر Idempotency-Key؛ پس از تلاش‌ها، Stop و هشدار.

تمرین کوتاه

تمرین · 10 دقیقه

هدف: انتخاب رفتار خطا.

گام‌ها: برای هر گره، On Error و Retry On Fail را انتخاب کن.

  1. «Get Customers» در ابتدای ورک‌فلوی خبرنامه؛ بدون آن کاری نمی‌شود کرد.
  2. «Send SMS» برای ۲۰۰ مشتری؛ اگر شماره یکی نامعتبر بود، بقیه باید بروند.
  3. «Log to Sheet» که فقط برای آمار است و شکستش اثری بر بقیه ندارد.
  4. «Create Invoice» در سامانه مالی (POST، بدون پشتیبانی کلید ایدمپوتنسی).

معیار پذیرش: ۱ Stop + Retry برای گذرا؛ ۲ خروجی خطا به صف؛ ۳ Continue قابل دفاع با ثبت؛ ۴ Stop بدون Retry خودکار.

راه‌حل نمونه

۱: Stop Workflow؛ Retry On Fail روشن برای قطعی گذرا. ۲: Continue (using error output) و شاخه خطا به صف بررسی شماره‌ها؛ Retry فقط اگر خطاها گذرا باشند. ۳: Continue قابل دفاع است چون اثری بر بقیه ندارد، ولی ورک‌فلوی خطا یا شمارش شکست‌ها باید ثبتش کند. ۴: Stop Workflow و بدون Retry خودکار، چون تکرار POST بدون کلید ایدمپوتنسی ممکن است فاکتور تکراری بسازد؛ پیش از هر تکرار، وجود فاکتور بررسی شود (دستی یا با یک GET).

چالش

تمرین · 30 دقیقه

موقعیت: ورک‌فلوی کار خودت (از درس‌های قبل) را برای خطا آماده کن. اگر سرویس‌ها واقعی و حساس‌اند، با API آزمایشی یا داده ساختگی بیازما.

  1. جدول همه گره‌ها: On Error و Retry On Fail هرکدام با دلیل یک‌خطی.
  2. ورک‌فلوی خطا با هشدار چهارجزئی و بدون داده آیتم؛ آن را با Stop And Error بیازما.
  3. دست‌کم یک خطای منطقی (مثل نتیجه خالی غیرعادی) را با If و Stop And Error بگیر.
  4. یک اجرای ناموفق عمدی را با داده خودش بازتولید و اصلاح کن و گام‌ها را بنویس.

خروجی مورد انتظار: جدول تنظیم گره‌ها، ورک‌فلوی خطا با یک هشدار نمونه، شرط خطای منطقی، و گزارش کوتاه بازتولید و اصلاح.

معیار پذیرش:

  • هیچ گره اقدامی Continue ساده ندارد مگر با دلیل روشن.
  • Retry On Fail روی گره‌هایی که بیشتر خطای ورودی یا کلید می‌گیرند خاموش است.
  • هشدار نمونه هیچ داده شخصی ندارد و قابل اقدام است.
  • داده آزمون ساختگی یا ناشناس است.

پرسش‌های سنجش

جمع‌بندی

  • پیش‌فرض Stop Workflow است؛ Continue تقریباً هرگز برای اقدام؛ خروجی خطا وقتی یک آیتم شکست می‌خورد و بقیه باید بروند.
  • Retry On Fail فقط برای خطای گذرا؛ برای سقف نرخ، دسته‌بندی؛ برای POST، کلید ایدمپوتنسی.
  • ورک‌فلوی خطا با Error Trigger؛ هشدار با نام ورک‌فلو، گره، خطا و پیوند، بدون داده آیتم.
  • خطای منطقی را با Stop And Error به خطای دیده‌شده تبدیل کن.
  • اجرای ناموفق را با داده خودش بازتولید کن (Debug in editor یا سنجاق دستی).
  • ورک‌فلوی خطا را هم بیازما.

پرسش‌های سنجش

در ورک‌فلوی «پیامک تأیید سفارش» گره Get Order و گره Send SMS پشت سر هم‌اند. برای هرکدام On Error را انتخاب کن و بگو چرا Continue برای Send SMS یا گره‌های بعدش خطرناک است.

پاسخ نمونه و معیار ارزیابی

Get Order: Stop Workflow، چون بدون داده سفارش پیامک بی‌معنی است. Send SMS: اگر چند آیتم است، Continue (using error output) با شاخه صف بررسی؛ اگر یک آیتم، Stop. Continue ساده خطرناک است چون با آخرین داده معتبر ادامه می‌دهد و ممکن است پیام با داده آیتم دیگر یا ناقص ساخته شود و گره‌های بعد (مثل ثبت «ارسال شد») اجرا شوند در حالی که ارسال نشده است.

  • Stop برای Get Order (1 امتیاز)
  • خروجی خطا برای Send SMS چندآیتمی (1 امتیاز)
  • خطر Continue با داده قبلی (1 امتیاز)
  • Continue برای همه ← ورک‌فلو «سبز» می‌ماند ولی داده غلط به مشتری می‌رسد.

گره Create Ticket با Retry On Fail (۵ تلاش، فاصله ۱ ثانیه) گاهی تیکت تکراری می‌سازد و گاهی پس از ۵ تلاش هنوز 429 می‌گیرد. دو ایراد طراحی و اصلاح هرکدام را بنویس.

پاسخ نمونه و معیار ارزیابی

(۱) POST بدون کلید ایدمپوتنسی تکرار می‌شود؛ وقتی تلاش اول در واقع ثبت شده (مثلاً timeout)، تلاش بعدی تیکت تازه می‌سازد. اصلاح: هدر Idempotency-Key از شناسه پیام. (۲) فاصله ثابت ۱ ثانیه برای 429 کافی نیست و تلاش‌ها هم در سقف شمرده می‌شوند. اصلاح: دسته‌بندی درخواست‌ها (Batching یا Loop Over Items با Wait) و فاصله بیشتر؛ پس از تلاش‌ها Stop و هشدار.

  • ایدمپوتنسی برای POST (1 امتیاز)
  • فاصله ثابت برای 429 ناکافی (1 امتیاز)
  • دسته‌بندی یا هشدار پس از تلاش‌ها (1 امتیاز)
  • تلاش را به ۱۰ برسان ← تکرار بیشتر هم تیکت تکراری بیشتر می‌سازد و هم سقف را بیشتر پر می‌کند.

متن هشداری که ورک‌فلوی خطا (با Error Trigger) برای مسئول می‌فرستد را با Expression طراحی کن. چه فیلدهایی می‌آیند و چه چیزی عمداً نمی‌آید؟

پاسخ نمونه و معیار ارزیابی

نمونه: «[هشدار] ورک‌فلو {{ $json.workflow.name }} در گره {{ $json.execution.lastNodeExecuted }} شکست خورد: {{ $json.execution.error.message }} — جزئیات: {{ $json.execution.url }}». می‌آید: نام ورک‌فلو، آخرین گره، پیام خطا، نشانی اجرا (و زمان). نمی‌آید: داده آیتم‌ها، متن پیام مشتری، بدنه پاسخ و هر کلید؛ جزئیات از راه پیوند اجرا با دسترسی کنترل‌شده دیده می‌شود.

  • نام ورک‌فلو و آخرین گره (1 امتیاز)
  • پیام خطا و پیوند اجرا (1 امتیاز)
  • حذف عمدی داده آیتم و داده حساس (1 امتیاز)
  • کل داده اجرا را بفرست ← کانال هشدار دسترسی گسترده‌تری دارد؛ داده مشتری نباید آنجا برود.

API گزارش فروش امروز صفر سفارش برگردانده، بدون هیچ خطای HTTP؛ ولی امروز روز کاری است و معمولاً ده‌ها سفارش هست. بهترین طراحی کدام است؟

  • گزارش خالی را بفرست؛ API خطا نداده است.
  • If برای «صفر سفارش در روز کاری» و گره Stop And Error تا ورک‌فلوی خطا هشدار بدهد.
  • Retry On Fail را روی گره API روشن کن.
  • On Error را روی Continue بگذار.
پاسخ نمونه و معیار ارزیابی
  • a ← گزارش خالی بی‌صدا ممکن است نشانه قطعی منبع داده باشد.
  • c ← گره خطا نداده؛ Retry اجرا نمی‌شود.
  • d ← هیچ خطایی نیست که Continue بر آن اثر بگذارد.

گره Code در ورک‌فلوی خلاصه هفتگی دیشب با «Cannot read properties of undefined (reading 'length')» شکست خورد و امروز صبح با داده تازه درست اجرا می‌شود. چطور علت را پیدا و اصلاح می‌کنی؟

پاسخ نمونه و معیار ارزیابی

اجرای ناموفق دیشب را از فهرست اجراها باز می‌کنم، ورودی گره Code را می‌بینم و آیتمی را پیدا می‌کنم که فیلد مورد انتظار (فهرستی که length آن خوانده شده) را ندارد. با Debug in editor (اگر نسخه دارد) یا سنجاق دستی همان ورودی، خطا را بازتولید می‌کنم؛ سپس کد را طوری اصلاح می‌کنم که وجود فیلد را بررسی کند یا آیتم ناقص را به مسیر جدا بفرستد؛ و همان ورودی را به‌عنوان آزمون نگه می‌دارم.

  • استفاده از داده همان اجرای ناموفق (1 امتیاز)
  • بازتولید با Debug in editor یا سنجاق (1 امتیاز)
  • اصلاح با بررسی وجود فیلد یا مسیر جدا (1 امتیاز)
  • امروز درست است پس مشکلی نیست ← داده ناقص دوباره می‌آید؛ تا علت را با داده خودش نبینی، اصلاح نشده است.

فایل‌های درس

نقطه‌های /flaky و /limited و /tickets برای ساختن خطا

barg-sabz-mock-api.py

پنج اجرای ناموفق با پاسخ مرجع

failure-cases.md

ابزارها و جایگزین‌ها

  • n8n 2.x — تنظیم خطا و اشکال‌زدایی — n8n Cloud در صورت دسترسی قانونی — مسیر بدون نصب
  • Python 3.9 یا بالاتر — API آزمایشی با نقطه‌های ناپایدار — مسیر بدون نصب

منابع

Work with nodes (node settings) n8n accessed 2026-10-16

Handle errors gracefully n8n accessed 2026-10-16

Debug and re-run past executions n8n accessed 2026-10-16

دوره

n8n از پایه