وقتی یک Workflow در n8n اجرا می‌شود، ممکن است در هر مرحله با خطا مواجه شود؛ برای مثال، اتصال به یک API برقرار نشود، سرویس خارجی پاسخ نامعتبر بدهد، اطلاعات مورد انتظار وجود نداشته باشد یا یک سرویس موقتاً از دسترس خارج شود.
اگر برای چنین شرایطی برنامه‌ای نداشته باشید، ممکن است اجرای Workflow متوقف شود و تا زمانی که خودتان اجرای ناموفق را بررسی نکنید، متوجه مشکل نشوید.
مدیریت خطا در n8n به شما کمک می‌کند خطاهای Workflowها را شناسایی کنید، جزئیات آن‌ها را ثبت کنید، اعلان دریافت کنید و در صورت امکان، فرایندهای بازیابی را اجرا کنید.
در این آموزش یاد می‌گیریم چگونه یک Error Workflow بسازیم و خطاهای گردش‌کارهای دیگر را به‌صورت متمرکز مدیریت کنیم.
مدیریت خطا در n8n چیست؟
مدیریت خطا یا Error Management مجموعه‌ای از روش‌ها برای شناسایی، ثبت، گزارش‌دهی و واکنش به خطاهای یک Workflow است.
برای مثال، فرض کنید Workflow شما اطلاعات سفارش‌های یک فروشگاه اینترنتی را دریافت می‌کند و آن‌ها را برای تیم فروش در تلگرام می‌فرستد.
اگر API فروشگاه با خطا مواجه شود، چند اتفاق ممکن است رخ دهد:
- اجرای Workflow ناموفق شود.
- سفارش به مقصد موردنظر ارسال نشود.
- شما از بروز مشکل مطلع نشوید.
- اطلاعات سفارش تا زمان بررسی مشکل پردازش نشوند.
با پیاده‌سازی مدیریت خطا می‌توانید یک گردش‌کار اختصاصی ایجاد کنید تا پس از وقوع خطا، اطلاعات اجرای ناموفق را دریافت کند و گزارشی برای شما ارسال کند.
البته باید توجه داشته باشید که ثبت و گزارش خطا به‌تنهایی به معنای رفع آن نیست. برای بازیابی خودکار باید مشخص کنید در هر نوع خطا چه اقدامی لازم است.
تفاوت Error Handling و Error Workflow در n8n
در n8n می‌توان خطاها را در دو سطح مدیریت کرد.
۱. مدیریت خطا در داخل Workflow
در این روش، رفتار یک Node را هنگام بروز خطا تنظیم می‌کنید. بسته به تنظیمات و نسخه n8n، می‌توانید اجرای Workflow را متوقف کنید، اجرای آن را ادامه دهید یا مسیر مشخصی را برای پردازش خروجی خطا در نظر بگیرید.
این روش زمانی مفید است که می‌خواهید درباره خطای یک مرحله خاص تصمیم بگیرید.
۲. استفاده از Error Workflow
در این روش یک Workflow جداگانه می‌سازید که وظیفه آن رسیدگی به اجرای ناموفق Workflowهای دیگر است.
برای مثال، می‌توانید از یک Error Workflow مشترک برای چندین Workflow استفاده کنید تا در صورت شکست اجرا، اطلاعات خطا به تلگرام ارسال شود.
| ویژگی | مدیریت داخل Workflow | Error Workflow |
|---|---|---|
| محدوده استفاده | یک مرحله یا جریان مشخص | رسیدگی متمرکز به اجراهای ناموفق |
| کاربرد اصلی | کنترل رفتار هنگام خطا | گزارش‌دهی و اقدامات پس از شکست |
| ارسال اعلان | امکان‌پذیر | امکان‌پذیر |
| استفاده مجدد | معمولاً نیازمند تنظیم در هر جریان | قابل استفاده برای چند Workflow |
این دو روش جایگزین کامل یکدیگر نیستند؛ در بسیاری از پروژه‌ها استفاده هم‌زمان از آن‌ها نتیجه بهتری دارد.
آموزش ساخت Error Workflow در n8n
در این بخش یک گردش‌کار اختصاصی می‌سازیم که اطلاعات خطا را دریافت کند و امکان ارسال گزارش آن را فراهم کند.
مرحله اول: ساخت یک Workflow جدید
وارد پنل n8n شوید و یک Workflow جدید ایجاد کنید.
نام پیشنهادی:
Central Error Handler
این Workflow قرار است مسئول دریافت اطلاعات اجرای ناموفق و پردازش گزارش خطا باشد.
مرحله دوم: اضافه کردن Error Trigger
در محیط طراحی Workflow، یک Node با نام Error Trigger اضافه کنید.
این Node برای دریافت اطلاعات خطا از Workflowهایی استفاده می‌شود که به این گردش‌کار اختصاص داده شده‌اند.
نکته مهم: Error Trigger معمولاً با اجرای عادی یا فشردن دکمه اجرای دستی، یک خطای آزمایشی تولید نمی‌کند. برای آزمایش آن باید از سازوکار فراخوانی Error Workflow استفاده کنید؛ مثلاً یک Workflow آزمایشی را به آن متصل کنید و عمداً در آن خطا ایجاد کنید.
مرحله سوم: شناخت اطلاعات دریافتی
پس از اجرای واقعی Error Workflow، خروجی Error Trigger را بررسی کنید. ساختار دقیق اطلاعات به نوع خطا و نسخه n8n بستگی دارد، اما معمولاً اطلاعاتی مانند موارد زیر در دسترس است:
- نام Workflow ناموفق
- شناسه اجرای ناموفق
- اطلاعات خطا و پیام آن
- اطلاعات مربوط به مرحله‌ای که با خطا مواجه شده است، در صورت موجود بودن
برای مشاهده ساختار دقیق داده‌ها، یک اجرای آزمایشی ناموفق ایجاد کنید و خروجی Node را در پنل اجرای n8n بررسی کنید.
این کار مهم است؛ چون نباید بدون بررسی خروجی واقعی فرض کنید تمام فیلدهای مربوط به Node، پیام خطا یا URL اجرای ناموفق همیشه وجود دارند.
مرحله چهارم: ارسال گزارش خطا به تلگرام
یکی از کاربردهای مهم Error Workflow، ارسال اعلان فوری به مدیر سیستم است.
برای این کار، ابتدا یک ربات تلگرام ایجاد کنید و اعتبارنامه آن را در بخش Credentials مربوط به n8n ذخیره کنید. سپس یک Node از نوع Telegram به Workflow اضافه کنید و عملیات ارسال پیام را انتخاب کنید.
در فیلد متن پیام، می‌توانید با استفاده از Expressions داده‌های دریافتی از Error Trigger را قرار دهید.
برای نمونه، قالب مفهومی پیام می‌تواند به این شکل باشد:
⚠️ خطا در اجرای Workflow
نام Workflow: [نام Workflow]
شناسه اجرا: [شناسه اجرا]
پیام خطا: [پیام خطا]
لطفاً اجرای ناموفق را بررسی کنید.
مقادیر داخل کروشه صرفاً جای‌نگهدار هستند. برای استفاده واقعی، آن‌ها را با Expressionهای متناسب با خروجی مشاهده‌شده در Error Trigger جایگزین کنید.
بهتر است فیلدها را از پنل داده‌های ورودی انتخاب کنید تا مسیر دقیق آن‌ها با ساختار خروجی n8n شما مطابقت داشته باشد.
نکات امنیتی هنگام ارسال خطا
پیام خطا ممکن است شامل اطلاعات حساسی مانند آدرس‌های داخلی، داده‌های ورودی کاربران، جزئیات درخواست API یا بخشی از پاسخ سرویس‌ها باشد.
بنابراین:
- رمز عبور، API Key و Access Token را در پیام خطا قرار ندهید.
- اطلاعات شخصی کاربران را تا حد امکان حذف کنید.
- دسترسی ربات و کانال دریافت گزارش‌ها را محدود نگه دارید.
- در صورت نیاز، به‌جای ارسال جزئیات کامل، شناسه اجرا و خلاصه خطا را ارسال کنید.
مرحله پنجم: اتصال Error Workflow به Workflow اصلی
ساخت Error Workflow به‌تنهایی کافی نیست. باید آن را به‌عنوان گردش‌کار مدیریت خطا برای Workflow موردنظر تنظیم کنید.
مراحل کلی عبارت‌اند از:
- Workflow مدیریت خطا را ذخیره کنید.
- آن را فعال کنید تا برای فراخوانی آماده باشد.
- Workflow اصلی را باز کنید.
- وارد تنظیمات Workflow شوید.
- گزینه مربوط به Error Workflow را پیدا کنید.
- گردش‌کار
Central Error Handlerرا انتخاب کنید. - تغییرات را ذخیره کنید.
نام دقیق یا محل گزینه‌ها ممکن است با نسخه و رابط کاربری n8n متفاوت باشد.
پس از انجام این تنظیمات، در صورت شکست اجرای Workflow اصلی، n8n می‌تواند Error Workflow تعیین‌شده را فراخوانی کند.
اگر چند Workflow دارید، می‌توانید از یک Error Workflow مشترک برای آن‌ها استفاده کنید؛ البته بهتر است مطمئن شوید که گزارش خطاها نام و شناسه Workflow مبدأ را مشخص می‌کند.
آموزش آزمایش مدیریت خطا در n8n
برای اطمینان از درست کار کردن سیستم، یک Workflow آزمایشی بسازید.
ساخت Workflow آزمایشی
یک Workflow جدید ایجاد کنید و این Nodeها را در آن قرار دهید:
- Manual Trigger
- یک Node که عمداً با خطا مواجه شود؛ برای مثال، یک Code Node با خطای آزمایشی
در Code Node می‌توانید از کد زیر استفاده کنید:
throw new Error('Test error for n8n error workflow');
این کد صرفاً برای آزمایش است و باعث ناموفق شدن اجرای Workflow می‌شود.
سپس Error Workflow را در تنظیمات همین Workflow آزمایشی انتخاب کنید و گردش‌کار اصلی را اجرا کنید.
نتیجه مورد انتظار
اگر تنظیمات درست باشند:
- اجرای Workflow آزمایشی ناموفق می‌شود.
- Error Workflow فراخوانی می‌شود.
- Error Trigger اطلاعات مربوط به خطا را دریافت می‌کند.
- Nodeهای بعدی می‌توانند گزارش خطا را ثبت یا ارسال کنند.
اگر پیامی دریافت نکردید، موارد زیر را بررسی کنید:
- آیا Error Workflow ذخیره و فعال شده است؟
- آیا آن را در تنظیمات Workflow اصلی انتخاب کرده‌اید؟
- آیا خطا در اجرای Workflow اصلی واقعاً رخ داده است؟
- آیا خود Error Workflow با خطا مواجه شده است؟
- آیا تنظیمات Credentials و مقصد ارسال پیام صحیح هستند؟
توجه داشته باشید که اگر Error Workflow نیز با خطا مواجه شود، ممکن است گزارش‌دهی کامل انجام نشود. بنابراین این گردش‌کار باید ساده، قابل‌اعتماد و تا حد امکان مستقل از سرویس‌های غیرضروری باشد.
ثبت خطاها در دیتابیس
ارسال پیام به تلگرام برای اطلاع‌رسانی سریع مناسب است، اما برای تحلیل بلندمدت بهتر است خطاها را در یک دیتابیس نیز ثبت کنید.
برای مثال، می‌توانید یک جدول با ساختار زیر داشته باشید:
| فیلد | کاربرد |
|---|---|
| workflow_name | نام Workflow |
| execution_id | شناسه اجرای ناموفق |
| error_message | خلاصه پیام خطا |
| failed_at | زمان وقوع خطا |
| status | وضعیت بررسی یا رسیدگی |
در Error Workflow می‌توانید پس از دریافت خطا، اطلاعات موردنیاز را با استفاده از Node دیتابیس در جدول ذخیره کنید.
این کار امکان می‌دهد بعداً بررسی کنید:
- کدام Workflow بیشترین خطا را دارد؟
- چه خطاهایی بیشتر تکرار می‌شوند؟
- آیا خطاها در ساعت خاصی افزایش پیدا می‌کنند؟
- کدام خطاها هنوز بررسی نشده‌اند؟
برای جلوگیری از ثبت اطلاعات حساس، پیش از ذخیره‌سازی، داده‌های خطا را بررسی و پاک‌سازی کنید. همچنین اگر می‌خواهید هر اجرای ناموفق فقط یک بار ثبت شود، می‌توانید شناسه اجرا را به‌عنوان بخشی از سازوکار جلوگیری از رکوردهای تکراری در نظر بگیرید.
آیا باید بعد از هر خطا Workflow را دوباره اجرا کنیم؟
خیر. اجرای مجدد خودکار همیشه راه‌حل مناسبی نیست.
برای مثال، اگر درخواست ارسال سفارش به یک API با Timeout مواجه شود، ممکن است درخواست در سمت سرویس مقصد انجام شده باشد، اما پاسخ آن به n8n نرسیده باشد. اجرای مجدد بدون بررسی وضعیت سفارش می‌تواند باعث ثبت سفارش تکراری شود.
بهتر است پیش از طراحی بازیابی خودکار، نوع خطا را مشخص کنید.
خطاهای موقت
نمونه‌ها:
- قطعی کوتاه‌مدت شبکه
- پاسخ موقتاً ناموفق سرویس خارجی
- محدودیت تعداد درخواست‌ها (Rate Limit)
برای این موارد می‌توان از Retry، تأخیر و تلاش مجدد کنترل‌شده استفاده کرد؛ به شرط آنکه عملیات قابلیت اجرای مجدد امن داشته باشد.
خطاهای دائمی یا مربوط به داده
نمونه‌ها:
- اطلاعات ضروری وجود ندارد.
- قالب داده نامعتبر است.
- اعتبارنامه منقضی شده است.
- دسترسی لازم به سرویس وجود ندارد.
در این شرایط، اجرای مجدد بدون اصلاح علت اصلی معمولاً مشکل را حل نمی‌کند. بهتر است خطا ثبت شود و اقدام مناسب، مانند اصلاح داده یا تمدید اعتبارنامه، انجام شود.
برای آشنایی با تلاش مجدد پس از خطا، می‌توانید مقاله «آموزش Retry در n8n؛ تلاش مجدد خودکار پس از خطا» را نیز مطالعه کنید.
تفاوت Error Workflow با ذخیره Executionها
Error Workflow برای واکنش به اجرای ناموفق و انجام کارهایی مانند ارسال اعلان یا ثبت گزارش استفاده می‌شود.
در مقابل، ذخیره‌سازی Executionها به شما امکان می‌دهد اجرای قبلی را در پنل n8n بررسی کنید و جزئیات بیشتری از ورودی‌ها و خروجی Nodeها ببینید.
این دو قابلیت مکمل یکدیگرند:
- Error Workflow به شما کمک می‌کند سریع از خطا مطلع شوید.
- Executionهای ذخیره‌شده برای بررسی علت خطا و عیب‌یابی مفید هستند.
- دیتابیس گزارش خطا می‌تواند برای ساخت داشبورد یا گزارش‌های آماری استفاده شود.
سیاست ذخیره‌سازی Executionها را متناسب با نیاز عملیاتی، فضای ذخیره‌سازی و ملاحظات حریم خصوصی تنظیم کنید.
بهترین روش‌ها برای مدیریت خطا در n8n
برای ساخت Workflowهای قابل‌اعتماد، نکات زیر را در نظر بگیرید:
- از Error Workflow مشترک استفاده کنید. برای پروژه‌های دارای چندین Workflow، یک مسیر استاندارد برای گزارش خطاها ایجاد کنید.
- گزارش قابل‌فهم بسازید. نام Workflow، شناسه اجرا و خلاصه خطا را در گزارش قرار دهید.
- خطاهای موقت را از دائمی جدا کنید. برای هر خطا سیاست بازیابی مناسبی داشته باشید.
- از اجرای تکراری عملیات حساس جلوگیری کنید. در پرداخت، ثبت سفارش و ارسال اطلاعات، از کنترل تکرار و سازوکارهای idempotency استفاده کنید.
- خود Error Workflow را آزمایش کنید. خطا در سرویس اعلان یا دیتابیس نباید بدون بررسی باقی بماند.
- اطلاعات حساس را حذف کنید. گزارش خطا نباید به محل انتشار رمزها و توکن‌ها تبدیل شود.
- Executionها را متناسب با نیاز نگه دارید. ذخیره بیش از حد داده‌ها می‌تواند مصرف فضای ذخیره‌سازی را افزایش دهد.
- خطاهای پرتکرار را تحلیل کنید. تکرار یک خطا معمولاً نشانه مشکلی است که باید در منبع آن برطرف شود.
جمع‌بندی
مدیریت خطا در n8n یکی از بخش‌های مهم ساخت اتوماسیون‌های قابل‌اعتماد است. با ایجاد Error Workflow می‌توانید خطاهای اجرای Workflowهای مختلف را در یک مسیر متمرکز دریافت کنید، آن‌ها را در دیتابیس ثبت کنید و از طریق تلگرام یا سرویس‌های دیگر اعلان بفرستید.
با این حال، گزارش خطا تنها قدم اول است. برای ساخت یک سیستم پایدار باید علت خطاها را بررسی کنید، برای خطاهای موقت سیاست Retry داشته باشید و از اجرای تکراری عملیات حساس جلوگیری کنید.
اگر در ابتدای مسیر یادگیری n8n هستید، پیشنهاد می‌شود ابتدا با مفاهیمی مانند Workflow، Node، Trigger و Webhook آشنا شوید و سپس مدیریت خطا و گزارش‌دهی را به پروژه‌های خود اضافه کنید.
سوالات متداول
Error Workflow در n8n چیست؟
Error Workflow یک گردش‌کار اختصاصی است که می‌تواند پس از شکست اجرای Workflowهای تنظیم‌شده، اطلاعات خطا را دریافت کند و اقداماتی مانند ارسال اعلان یا ثبت گزارش را انجام دهد.
آیا می‌توان از یک Error Workflow برای چند Workflow استفاده کرد؟
بله. می‌توانید یک Error Workflow مشترک بسازید و آن را در تنظیمات چند Workflow انتخاب کنید. بهتر است گزارش‌ها شامل نام و شناسه اجرای Workflow مبدأ باشند.
آیا Error Trigger را می‌توان مانند Manual Trigger اجرا کرد؟
Error Trigger برای دریافت اطلاعات خطا از سازوکار Error Workflow طراحی شده است. برای آزمایش آن، یک Workflow اصلی را طوری تنظیم کنید که در شرایط آزمایشی ناموفق شود و Error Workflow مربوط به آن را فراخوانی کند.
آیا Error Workflow خطای اصلی را خودکار برطرف می‌کند؟
خیر. Error Workflow می‌تواند خطا را گزارش کند یا اقدامات دیگری انجام دهد، اما رفع خودکار خطا به منطق بازیابی‌ای بستگی دارد که خودتان طراحی می‌کنید.
برای ارسال خطاهای n8n به تلگرام چه چیزی لازم است؟
به یک ربات تلگرام، Credentials معتبر در n8n، یک Node برای ارسال پیام و یک Error Workflow نیاز دارید. سپس باید اطلاعات خطا را با Expressions مناسب در متن پیام قرار دهید.
آیا ذخیره Executionها برای مدیریت خطا کافی است؟
ذخیره Executionها برای بررسی و عیب‌یابی مفید است، اما به‌تنهایی جایگزین اعلان و گزارش‌دهی فعال نیست. ترکیب ذخیره‌سازی Executionها، Error Workflow و ثبت گزارش می‌تواند دید بهتری از وضعیت اتوماسیون ایجاد کند.
