آموزش Debug Workflow در n8n؛ عیب‌یابی و رفع خطاها با مثال عملی

هنگام ساخت اتوماسیون با n8n، ممکن است Workflow در یک مرحله متوقف شود، داده‌های اشتباهی تولید کند یا خروجی مورد انتظار را به شما ندهد. گاهی نیز تمام Nodeها بدون نمایش خطای واضح اجرا می‌شوند، اما نتیجه نهایی با چیزی که انتظار دارید متفاوت است.

در چنین شرایطی، به‌جای تغییر تصادفی تنظیمات یا ساخت مجدد Workflow، باید از روش اصولی عیب‌یابی یا Debugging استفاده کنید.

در این مقاله یاد می‌گیرید چگونه Executionهای n8n را بررسی کنید، ورودی و خروجی Nodeها را ببینید، محل بروز خطا را پیدا کنید و یک Workflow خراب را مرحله‌به‌مرحله اصلاح کنید.

Debug در n8n چیست؟

Debugging یا عیب‌یابی به فرایند بررسی عملکرد یک برنامه یا اتوماسیون برای پیدا کردن علت بروز مشکل گفته می‌شود.

در n8n، این کار معمولاً با بررسی اجرای Workflow، مشاهده داده‌های ورودی و خروجی Nodeها، مطالعه پیام‌های خطا و آزمایش دوباره مراحل انجام می‌شود.

برای مثال، فرض کنید یک Workflow اطلاعات سفارش را از یک API دریافت می‌کند، مبلغ سفارش را محاسبه می‌کند و سپس اطلاعات را به تلگرام می‌فرستد.

اگر پیام تلگرام مبلغ اشتباهی داشته باشد، مشکل می‌تواند از چند بخش باشد:

• API مبلغ را با ساختار متفاوتی برگردانده است.
• Expression مقدار اشتباهی را می‌خواند.
• محاسبه در Code Node نادرست است.
• داده در یکی از Nodeهای میانی تغییر کرده است.
• پیام نهایی از فیلد دیگری استفاده می‌کند.

با Debug کردن Workflow می‌توانید مشخص کنید مشکل دقیقاً از کدام مرحله شروع شده است.

تفاوت Debugging با Error Handling چیست؟

این دو مفهوم به یکدیگر مرتبط هستند، اما کاربرد یکسانی ندارند.

Debugging برای پیدا کردن علت مشکل و اصلاح آن استفاده می‌شود.

Error Handling برای تعیین رفتار سیستم هنگام بروز خطا به کار می‌رود؛ برای مثال، ثبت خطا، ارسال اعلان، اجرای مسیر جایگزین یا مدیریت تلاش مجدد.

در پروژه‌های حرفه‌ای به هر دو نیاز دارید. حتی اگر Error Handling مناسبی داشته باشید، برای رفع یک خطای تکرارشونده ممکن است همچنان لازم باشد Workflow را Debug کنید.

برای مطالعه بیشتر می‌توانید مقاله «آموزش Error Handling در n8n؛ مدیریت خطاها و جلوگیری از توقف Workflow» را نیز بخوانید.

آشنایی با Execution در n8n

هر بار که یک Workflow اجرا می‌شود، اطلاعاتی درباره آن اجرا در n8n ثبت می‌شود. به این اجرای مشخص، Execution گفته می‌شود.

بسته به نوع اجرا، تنظیمات ذخیره‌سازی و نسخه n8n، ممکن است اطلاعات اجراهای موفق، ناموفق یا در حال اجرا در دسترس باشند.

Execution یکی از مهم‌ترین منابع اطلاعاتی برای عیب‌یابی است؛ زیرا می‌توانید بررسی کنید:

• Workflow در چه وضعیتی قرار گرفته است.
• کدام Nodeها اجرا شده‌اند.
• اجرای کدام مرحله با خطا مواجه شده است.
• ورودی و خروجی Nodeها چه بوده است.
• پیام خطای ثبت‌شده چه اطلاعاتی دارد.

چگونه Execution را بررسی کنیم؟

برای عیب‌یابی یک Workflow، مراحل زیر را دنبال کنید:

1. Workflow مورد نظر را در محیط n8n باز کنید.
2. بخش مربوط به Executions یا تاریخچه اجراها را باز کنید.
3. اجرای مورد نظر را بر اساس زمان و وضعیت آن پیدا کنید.
4. جزئیات اجرای انتخاب‌شده را باز کنید.
5. Nodeهای اجراشده و Nodeهایی را که با خطا مواجه شده‌اند بررسی کنید.
6. ورودی، خروجی و پیام خطای Node مشکل‌دار را مشاهده کنید.

نام بخش‌ها و محل قرارگیری گزینه‌ها ممکن است بر اساس نسخه n8n یا نوع نمای مورد استفاده متفاوت باشد.

نکته مهم این است که اجرای جدید لزوماً اطلاعات اجرای قبلی را بازتولید نمی‌کند. اگر مشکل در یک Execution مشخص رخ داده است، همان اجرا را بررسی کنید؛ البته دسترسی به جزئیات آن به تنظیمات ذخیره‌سازی و وضعیت داده‌های اجرا بستگی دارد.

آموزش Debug کردن Workflow با یک مثال عملی

فرض کنید یک Workflow ساخته‌اید که اطلاعات سفارش را از یک API دریافت می‌کند و سپس مبلغ سفارش را در پیام تلگرام نمایش می‌دهد.

ساختار Workflow به شکل زیر است:

Manual Trigger

      |

      v

HTTP Request

      |

      v

Edit Fields

      |

      v

Telegram

هدف این است که مبلغ سفارش از API دریافت شود و در پیام تلگرام نمایش داده شود.

اما هنگام اجرا، پیام ارسالی به‌جای مبلغ واقعی، مقدار خالی یا undefined نشان می‌دهد.

برای مثال، پیام خروجی به این شکل است:

مبلغ سفارش: undefined

در ادامه، مرحله‌به‌مرحله علت این مشکل را پیدا می‌کنیم.

مرحله اول: بررسی خروجی HTTP Request

ابتدا Execution را باز کنید و Node مربوط به HTTP Request را انتخاب کنید.

خروجی این Node را بررسی کنید تا مشخص شود API چه داده‌ای برگردانده است.

فرض کنید پاسخ API به این صورت باشد:

{

  "order": {

    "id": 125,

    "total_amount": 850000

  }

}

در این مثال، مبلغ سفارش در مسیر زیر قرار دارد:

order.total_amount

بنابراین اگر در Node بعدی از مسیر amount استفاده کنید، به مقدار مورد نظر دسترسی پیدا نمی‌کنید.

در عیب‌یابی همیشه ابتدا داده واقعی را بررسی کنید؛ نام فیلدها را بر اساس حدس یا ساختار مورد انتظار خودتان انتخاب نکنید.

مرحله دوم: بررسی Expression

فرض کنید در Node مربوط به Edit Fields از Expression زیر استفاده کرده‌اید:

{{ $json.amount }}

این عبارت به دنبال فیلدی با نام amount در داده فعلی می‌گردد، اما در پاسخ نمونه چنین فیلدی وجود ندارد.

اگر ساختار خروجی HTTP Request همان JSON بالا باشد، Expression مناسب برای دسترسی به مبلغ می‌تواند این باشد:

{{ $json.order.total_amount }}

پس از اصلاح Expression، Node را دوباره اجرا کنید و بررسی کنید که مقدار مورد انتظار تولید شده باشد.

مرحله سوم: بررسی خروجی Edit Fields

بعد از اصلاح Expression، خروجی Edit Fields را بررسی کنید.

خروجی مورد انتظار باید شامل فیلدی مشابه زیر باشد:

{

  "amount": 850000

}

اگر خروجی هنوز خالی است، بررسی کنید:

• Expression در حالت صحیح تنظیم شده باشد.
• نام فیلدها دقیق باشد.
• ساختار داده ورودی با Expression مطابقت داشته باشد.
• تنظیمات Edit Fields باعث حذف یا تغییر ناخواسته فیلدها نشده باشند.

در این مرحله بهتر است تنها یک مشکل را در هر بار اصلاح کنید تا مشخص شود کدام تغییر باعث رفع خطا شده است.

مرحله چهارم: بررسی پیام تلگرام

در نهایت Node تلگرام را بررسی کنید.

اگر در متن پیام از Expression زیر استفاده شده باشد:

{{ $json.amount }}

و ورودی این Node شامل فیلد amount باشد، مقدار آن در پیام قرار می‌گیرد.

پیام نهایی می‌تواند چنین باشد:

سفارش شماره 125

مبلغ سفارش: 850000

این مثال نشان می‌دهد که مشکل ظاهری در پیام تلگرام بود، اما علت اصلی در مسیر دسترسی به داده‌های خروجی API قرار داشت.

چگونه ورودی و خروجی Nodeها را بررسی کنیم؟

یکی از مهم‌ترین روش‌های Debug در n8n، بررسی داده‌ها در هر مرحله است.

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

برای عیب‌یابی، این ترتیب را رعایت کنید:

1. آخرین Nodeای را که خروجی اشتباه دارد مشخص کنید.
2. خروجی Node قبلی را بررسی کنید.
3. ورودی Node مشکل‌دار را مشاهده کنید.
4. تنظیمات و Expressionهای آن را بررسی کنید.
5. پس از اصلاح، نتیجه را دوباره آزمایش کنید.

برای مثال، اگر HTTP Request داده صحیحی برمی‌گرداند، اما Edit Fields مقدار اشتباهی تولید می‌کند، احتمالاً باید تنظیمات Edit Fields یا Expressionهای آن را بررسی کنید؛ نه اینکه بدون دلیل تنظیمات API را تغییر دهید.

بررسی تعداد Itemها

در n8n، داده‌ها معمولاً به شکل یک یا چند Item بین Nodeها منتقل می‌شوند.

فرض کنید یک API به‌جای یک مشتری، اطلاعات ۲۰ مشتری را برمی‌گرداند. اگر تصور کنید فقط یک Item وجود دارد، ممکن است رفتار Workflow با انتظار شما متفاوت باشد.

هنگام Debug علاوه بر مقدار فیلدها، به تعداد Itemها نیز توجه کنید.

بررسی کنید:

• آیا Node ورودی دریافت کرده است؟
• چند Item تولید شده است؟
• آیا همه Itemها پردازش شده‌اند؟
• آیا یکی از مراحل داده‌ها را فیلتر کرده است؟
• آیا خروجی فقط شامل بخشی از اطلاعات ورودی است؟

این بررسی به‌خصوص هنگام استفاده از IF، Merge، Loop Over Items و Code Node اهمیت دارد.

عیب‌یابی Expressionها در n8n

Expressionها برای خواندن داده‌های پویا از Nodeهای دیگر یا داده فعلی استفاده می‌شوند. اشتباه در مسیر فیلدها یکی از دلایل متداول خروجی‌های نادرست است.

برای مثال، اگر داده شما به این شکل باشد:

{

  "customer": {

    "name": "Ali Ahmadi",

    "email": "ali@example.com"

  }

}

برای دریافت نام مشتری از داده فعلی می‌توانید از این عبارت استفاده کنید:

{{ $json.customer.name }}

اما اگر از عبارت زیر استفاده کنید:

{{ $json.name }}

در این ساختار، فیلد name در سطح اصلی JSON وجود ندارد.

روش اصولی بررسی Expression

هنگام مشاهده مقدار خالی یا اشتباه، این موارد را بررسی کنید:

• ساختار واقعی JSON چیست؟
• نام فیلد دقیقاً چگونه نوشته شده است؟
• فیلد در سطح اصلی قرار دارد یا داخل یک شیء دیگر؟
• داده از کدام Node وارد شده است؟
• آیا در مرحله قبلی ساختار داده تغییر کرده است؟

اگر نیاز دارید داده را از یک Node مشخص بخوانید، در صورت مناسب بودن ساختار Workflow می‌توانید از ارجاع مستقیم به Node استفاده کنید؛ برای مثال:

{{ $('HTTP Request').first().json.order.total_amount }}

این عبارت نمونه‌ای از خواندن اولین Item خروجی Node با نام HTTP Request است. نام Node باید دقیقاً با نام واقعی آن در Workflow مطابقت داشته باشد و استفاده از .first() زمانی مناسب است که واقعاً اولین Item مورد نظر شما باشد.

اگر چند Item دارید یا به داده متناظر با Item فعلی نیاز دارید، باید روش ارجاع را متناسب با ساختار اجرا انتخاب کنید.

برای یادگیری بیشتر درباره این قابلیت، مقاله «آموزش Expressions در n8n؛ استفاده از داده‌های پویا در Workflow» را مطالعه کنید.

چگونه Code Node را Debug کنیم؟

اگر در Workflow از Code Node استفاده می‌کنید، ممکن است خطا از منطق JavaScript یا ساختار داده‌های ورودی باشد.

برای مثال، فرض کنید کد زیر را نوشته‌اید:

return $input.all().map(item => ({

  json: {

    name: item.json.customer.name,

    email: item.json.customer.email

  }

}));

این کد انتظار دارد هر Item دارای شیء customer باشد.

اگر یکی از Itemها چنین ساختاری نداشته باشد، ممکن است هنگام دسترسی به customer.name خطا رخ دهد.

مراحل عیب‌یابی Code Node

۱. ورودی را بررسی کنید.

مطمئن شوید تمام Itemها ساختار مورد انتظار را دارند.

۲. خطا را از متن پیام شناسایی کنید.

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

۳. فرضیات کد را بررسی کنید.

اگر احتمال می‌دهید بعضی Itemها فاقد customer باشند، باید تصمیم بگیرید که با چنین داده‌ای چه رفتاری داشته باشید.

۴. خروجی را آزمایش کنید.

پس از اصلاح، تعداد Itemها و ساختار خروجی را بررسی کنید.

برای مثال، می‌توانید قبل از دسترسی به فیلدهای داخلی، وجود شیء مورد نیاز را بررسی کنید:

return $input.all().map(item => {

  const customer = item.json.customer ?? {};



  return {

    json: {

      name: customer.name ?? null,

      email: customer.email ?? null

    }

  };

});

این نسخه در صورت نبودن customer یا فیلدهای name و email، مقدار null تولید می‌کند. البته این کار جایگزین اعتبارسنجی کامل نیست؛ اگر وجود ایمیل ضروری است، بهتر است داده نامعتبر به‌صورت صریح شناسایی و مدیریت شود.

عیب‌یابی HTTP Request و خطاهای API

یکی دیگر از بخش‌هایی که در Workflowهای n8n ممکن است مشکل ایجاد کند، ارتباط با APIهاست.

خطاهای HTTP Request می‌توانند دلایل مختلفی داشته باشند:

• آدرس API اشتباه باشد.
• توکن یا کلید دسترسی معتبر نباشد.
• ساختار درخواست با مستندات API هماهنگ نباشد.
• سرور مقصد پاسخ ناموفق برگرداند.
• ارتباط شبکه یا DNS دچار مشکل شود.
• محدودیت تعداد درخواست‌ها اعمال شده باشد.

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

چند نمونه از خطاهای رایج:

این کدها معانی رایج HTTP هستند و علت دقیق خطا باید با توجه به مستندات API مقصد بررسی شود.

اگر API پاسخ 429 می‌دهد، ممکن است استفاده از Retry، تأخیر بین درخواست‌ها یا محدود کردن نرخ ارسال مناسب باشد. اما اگر آدرس اشتباه باشد، تکرار درخواست مشکل را برطرف نمی‌کند.

تفاوت خطای Workflow با خروجی اشتباه

همه مشکلات Workflow با پیام خطا همراه نیستند.

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

برای مثال:

• مبلغ سفارش به‌اشتباه محاسبه شده است.
• پیام تلگرام شامل نام مشتری دیگری است.
• یک فیلد در خروجی نهایی وجود ندارد.
• تعداد Itemهای خروجی کمتر از انتظار است.
• Workflow اطلاعات قدیمی را پردازش می‌کند.

در این موارد، بررسی وضعیت موفق یا ناموفق Execution به‌تنهایی کافی نیست. باید صحت داده‌ها و منطق Workflow را نیز بررسی کنید.

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

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

نکات مهم هنگام Debug کردن Workflowهای در حال اجرا

در پروژه‌های عملیاتی، عیب‌یابی باید با توجه به اثر آن بر سرویس واقعی انجام شود.

۱. از اجرای دوباره عملیات حساس بدون بررسی خودداری کنید

اگر Workflow مسئول ارسال پیام، ثبت سفارش یا ثبت تراکنش باشد، اجرای دوباره آن ممکن است عملیات را تکرار کند.

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

۲. اطلاعات محرمانه را در گزارش‌ها منتشر نکنید

در داده‌های Execution ممکن است اطلاعاتی مانند توکن API، ایمیل، شماره تلفن یا داده‌های مشتری وجود داشته باشد.

هنگام ارسال تصویر خطا برای دیگران یا ثبت گزارش، اطلاعات حساس را حذف یا مخفی کنید.

۳. تنظیمات ذخیره‌سازی Execution را بررسی کنید

اگر جزئیات اجرای قدیمی در دسترس نیست، ممکن است تنظیمات ذخیره‌سازی، سیاست پاک‌سازی داده‌ها یا وضعیت Execution دلیل آن باشد.

برای پروژه‌هایی که به عیب‌یابی دقیق نیاز دارند، سیاست نگهداری اطلاعات اجرا را متناسب با نیاز عملیاتی و الزامات حریم خصوصی تنظیم کنید.

۴. تغییرات را مرحله‌به‌مرحله اعمال کنید

اگر هم‌زمان چند Node را تغییر دهید، پیدا کردن علت اصلی مشکل دشوارتر می‌شود.

بهتر است یک فرضیه را آزمایش کنید، نتیجه را ببینید و سپس به سراغ تغییر بعدی بروید.

چک‌لیست عیب‌یابی Workflow در n8n

وقتی Workflow نتیجه مورد انتظار را تولید نمی‌کند، از این چک‌لیست استفاده کنید:

• [ ] اجرای درست Workflow را در Executions پیدا کرده‌ام.
• [ ] پیام خطا و وضعیت Nodeهای اجراشده را بررسی کرده‌ام.
• [ ] ورودی و خروجی Node مشکل‌دار را دیده‌ام.
• [ ] ساختار واقعی JSON را بررسی کرده‌ام.
• [ ] Expressionها و نام فیلدها را کنترل کرده‌ام.
• [ ] تعداد Itemهای ورودی و خروجی را بررسی کرده‌ام.
• [ ] در صورت استفاده از API، کد وضعیت و پاسخ آن را بررسی کرده‌ام.
• [ ] پس از هر تغییر، نتیجه را دوباره آزمایش کرده‌ام.
• [ ] احتمال اجرای تکراری عملیات حساس را در نظر گرفته‌ام.
• [ ] اطلاعات محرمانه را در گزارش‌ها یا تصاویر افشا نکرده‌ام.

جمع‌بندی

Debug کردن Workflow در n8n به شما کمک می‌کند به‌جای حدس زدن، علت واقعی مشکلات را پیدا کنید. با بررسی Executionها، مشاهده ورودی و خروجی Nodeها، کنترل Expressionها و بررسی پاسخ APIها می‌توانید بسیاری از خطاهای رایج را سریع‌تر شناسایی کنید.

مهم‌ترین اصل این است که مشکل را از نزدیک‌ترین مرحله‌ای که خروجی آن با انتظار شما متفاوت است بررسی کنید و تغییرات را به‌صورت مرحله‌به‌مرحله انجام دهید.

اگر در حال ساخت اتوماسیون‌های حرفه‌ای با n8n هستید، یادگیری Debugging در کنار مدیریت خطا، استفاده از Retry و طراحی Sub-workflowها به شما کمک می‌کند Workflowهایی قابل اعتمادتر و ساده‌تر برای نگهداری بسازید.

سوالات متداول

چگونه خطای یک Node را در n8n پیدا کنیم؟

Execution مربوط به Workflow را باز کنید، Node مشکل‌دار را انتخاب کنید و جزئیات خطا، ورودی و خروجی آن را بررسی کنید. سپس تنظیمات Node و داده‌های ورودی را با ساختار مورد انتظار مقایسه کنید.

چرا Workflow در n8n اجرا می‌شود اما خروجی اشتباه دارد؟

ممکن است Expression اشتباه باشد، داده در یکی از مراحل تغییر کرده باشد، منطق محاسبه ایراد داشته باشد یا Workflow اطلاعات متفاوتی از انتظار شما دریافت کرده باشد. در این شرایط باید داده‌های ورودی و خروجی مراحل مختلف را بررسی کنید.

چرا مقدار یک فیلد در n8n برابر undefined است؟

معمولاً Expression به مسیری اشاره می‌کند که در داده واقعی وجود ندارد، نام فیلد اشتباه است یا ساختار ورودی با انتظار شما متفاوت است. ابتدا JSON واقعی را بررسی و سپس Expression را اصلاح کنید.

آیا می‌توان Workflow را بدون اجرای کامل Debug کرد؟

می‌توانید بخش‌های مختلف را جداگانه آزمایش کنید و از قابلیت اجرای Nodeها یا Workflow با داده‌های نمونه، در صورت پشتیبانی محیط و نسخه خود، استفاده کنید. با این حال، برخی مشکلات فقط هنگام اجرای کامل و تعامل Nodeها با یکدیگر ظاهر می‌شوند.

تفاوت Debug با Retry در n8n چیست؟

Debug برای پیدا کردن علت مشکل استفاده می‌شود، اما Retry برای تلاش مجدد پس از شکست یک عملیات به کار می‌رود. Retry لزوماً علت خطا را برطرف نمی‌کند و برای عملیات حساس باید احتمال تکرار ناخواسته را نیز در نظر گرفت.

اگر Execution قبلی در n8n موجود نباشد چه کار کنیم؟

تنظیمات ذخیره‌سازی و پاک‌سازی Executionها را بررسی کنید. اگر اطلاعات اجرای قبلی ذخیره نشده یا حذف شده باشد، ممکن است مجبور شوید با داده‌های نمونه، Workflow را دوباره آزمایش کنید؛ البته اجرای مجدد باید با توجه به احتمال تکرار عملیات جانبی انجام شود.