Unhandled Promise Rejection: خطای خاموشی که کاربر میبیند و شما نه

در این مقاله میخوانید
- یعنی چه؟
- چرا اینقدر رایج است
- ۱. فراموش کردن catch در زنجیره
- ۲. تابع async که صدا زده میشود ولی منتظرش نمیمانند
- ۳. خطای داخل then
- ۴. فرض اینکه fetch در برابر خطای سرور رد میشود
- ۵. Promise.all و شکست یکی از اعضا
- چطور بگیریمشان
- در سطح موضعی
- در سطح سراسری
- چرا کاربران گزارش نمیدهند
- چطور موجودیهای فعلی را پیدا کنیم
- در Node.js فرق میکند
- مثال واقعی: اسپینری که گاهی نمیایستد
- fetch دقیقاً کِی رد میشود؟
- نکتههای ظریف شنوندهٔ سراسری
- الگوهایی که مشکل را کم میکنند
- پرسشهای رایج
- چرا try/catch دور return fetchUser() خطا را نمیگیرد؟
- فرق .catch() با پارامتر دوم then چیست؟
- آیا forEach با تابع async امن است؟
- جمعبندی
- منابع و مطالعهٔ بیشتر
بعضی خطاها بلندند: صفحه میشکند، کنسول قرمز میشود، کسی خبردار میشود. و بعضی خطاها بیصدا هستند — کاربر میبیند که چیزی کار نکرد، ولی هیچجا ثبت نمیشود. Unhandled Promise Rejection از خانوادهٔ دوم است، و در کدهای مدرن جاوااسکریپت که تقریباً همهچیزشان ناهمزمان است، شایعترین عضو آن.
یعنی چه؟
هر Promise دو سرنوشت دارد: یا موفق میشود، یا رد میشود. وقتی رد میشود و هیچکس catchای برایش نگذاشته باشد، جاوااسکریپت رویداد unhandledrejection را منتشر میکند.
fetch('/api/user')
.then(r => r.json())
.then(u => render(u));
// اگر شبکه قطع باشد، اینجا هیچ catch ای نیست
تفاوت مهمش با خطای معمولی این است که اجرای بقیهٔ صفحه متوقف نمیشود. صفحه سالم میماند، فقط آن بخشی که منتظر داده بود هرگز پر نمیشود. کاربر یک اسپینر بیپایان میبیند یا بخشی خالی — و هیچ پیام خطایی در کار نیست.
چرا اینقدر رایج است
۱. فراموش کردن catch در زنجیره
سادهترین حالت. هر زنجیرهٔ then که به catch ختم نشود، یک بمب ساعتی است.
۲. تابع async که صدا زده میشود ولی منتظرش نمیمانند
async function saveDraft() { await api.save(draft); }
saveDraft(); // بدون await و بدون catch — رد شدنش بیصدا میماند
این الگو در هندلرهای رویداد بسیار رایج است و یکی از رایجترین منابع این خطاست.
۳. خطای داخل then
fetch('/api/user')
.then(r => r.json())
.then(u => document.getElementById('name').textContent = u.name)
.catch(e => console.log('خطای شبکه')); // پیام گمراهکننده
اگر عنصر name وجود نداشته باشد، یک TypeError رخ میدهد که وارد همان catch میشود و بهعنوان «خطای شبکه» گزارش میشود. catch انتهای زنجیره همهچیز را میگیرد، نه فقط خطای شبکه را.
۴. فرض اینکه fetch در برابر خطای سرور رد میشود
مهمترین سوءتفاهم دربارهٔ fetch: پاسخ ۵۰۰ یا ۴۰۴ باعث رد شدن Promise نمیشود. Promise با موفقیت resolve میشود و شما باید خودتان بررسی کنید:
const res = await fetch('/api/user');
if (!res.ok) throw new Error('HTTP ' + res.status); // بدون این خط، خطا خاموش میماند
const user = await res.json();
بدون آن خط، res.json() روی صفحهٔ خطای HTML اجرا میشود و خطای مبهم Unexpected token میدهد — که هیچ ربطی به مشکل واقعی ندارد.
۵. Promise.all و شکست یکی از اعضا
Promise.all با اولین شکست رد میشود. اگر میخواهید بقیه ادامه دهند، Promise.allSettled ابزار درست است.
چطور بگیریمشان
در سطح موضعی
try {
const res = await fetch('/api/user');
if (!res.ok) throw new Error('HTTP ' + res.status);
render(await res.json());
} catch (e) {
showError('بارگذاری اطلاعات ممکن نشد'); // به کاربر بگویید چه شد
report(e); // و خودتان هم بدانید
}
نکتهٔ کلیدی: هر دو کار را بکنید. فقط ثبت کردن یعنی کاربر همچنان اسپینر میبیند؛ فقط پیام دادن یعنی شما هرگز نمیفهمید چند نفر به این خوردهاند.
در سطح سراسری
تور ایمنی برای هر چیزی که از دستتان در رفته:
window.addEventListener('unhandledrejection', function (e) {
report({ type: 'unhandled_rejection', reason: String(e.reason), stack: e.reason?.stack });
});
و این نکته را حتماً بدانید: این رویداد جدا از window.onerror است. اگر فقط onerror را گوش میکنید، هیچکدام از این خطاها را نمیبینید. در کد امروزی که بیشتر منطقش ناهمزمان است، این یعنی بخش بزرگی از خطاهایتان نامرئی میمانند.
چرا کاربران گزارش نمیدهند
این خطا خصوصیت بدی دارد: از دید کاربر شبیه کندی است، نه شبیه خرابی. اسپینری که نمیایستد، فهرستی که خالی میماند، دکمهای که انگار چیزی نشد.
واکنش طبیعی کاربر این است که صفحه را رفرش کند یا اینترنتش را مقصر بداند. تقریباً هیچوقت به این فکر نمیکند که باگی رخ داده که ارزش گزارش دادن دارد. برای همین این خانواده از خطاها میتوانند ماهها زنده بمانند و در هیچ گزارشی نیایند. این رفتار فقط مخصوص این خطا نیست؛ چرا کاربران باگ گزارش نمیدهند را جداگانه بررسی کردهایم.
چطور موجودیهای فعلی را پیدا کنیم
احتمالاً همین حالا چند مورد از اینها در کدتان هست. سه راه برای پیدا کردنشان:
۱. در کنسول مرورگر بگردید. این خطاها در کنسول با متن Uncaught (in promise) ظاهر میشوند. یک بار مسیرهای اصلی سایت را با کنسول باز طی کنید — معمولاً چند مورد پیدا میشود.
۲. دنبال الگوهای مشکوک بگردید. در کد جستجو کنید:
.then( # هر زنجیرهای که به catch ختم نشود
async function # و هر تابعی که بدون await صدا زده شود
هر fetch که بعدش res.ok بررسی نشده، مورد بعدی است.
۳. شنوندهٔ سراسری را اضافه کنید و یک هفته صبر کنید. مؤثرترین راه، چون کاربران واقعی مسیرهایی میروند که شما نمیروید.
در Node.js فرق میکند
اگر کد سمت سرور هم دارید، بدانید که رفتار متفاوت است. در نسخههای جدید Node، یک Promise رد شده و مدیریتنشده باعث میشود کل پراسس متوقف شود — نه اینکه بیصدا رد شود. معادل مرورگری آن این است:
process.on('unhandledRejection', (reason) => {
logger.error({ reason }, 'unhandled rejection');
// در محیط production معمولاً بهتر است بعد از ثبت، تمیز خارج شوید
});
یعنی همان الگویی که در مرورگر یک خطای خاموش میسازد، روی سرور میتواند سرویس را بخواباند.
مثال واقعی: اسپینری که گاهی نمیایستد
نشانه: چند کاربر میگویند صفحهٔ «سفارشهای من» گاهی همیشه در حال بارگذاری میماند. شما هر بار امتحان میکنید، درست کار میکند.
async function loadOrders() {
showSpinner();
const res = await fetch('/api/orders');
renderOrders(await res.json());
hideSpinner();
}
loadOrders();
تشخیص: شنوندهٔ سراسری چند SyntaxError ثبت کرده که به res.json() اشاره میکنند؛ یعنی پاسخ بهجای JSON، صفحهٔ HTML بوده است. لاگهای سرور نشان میدهند که در ساعتهای شلوغ، gateway جلوی سرویس پاسخ ۵۰۲ با یک صفحهٔ HTML برمیگرداند. سه مشکل روی هم افتادهاند: res.ok بررسی نشده، خطا هیچجا گرفته نشده، و hideSpinner فقط در مسیر موفق اجرا میشود.
اصلاح:
async function loadOrders() {
showSpinner();
try {
const res = await fetch('/api/orders');
if (!res.ok) throw new Error('HTTP ' + res.status);
renderOrders(await res.json());
} catch (e) {
showError('بارگذاری سفارشها ممکن نشد');
report(e);
} finally {
hideSpinner(); // اسپینر در هر حالت خاموش میشود
}
}
بخش کلیدی finally است: هر کاری که باید در پایان — موفق یا ناموفق — انجام شود، آنجا میرود. حالا بهجای یک SyntaxError گمراهکننده، گزارش HTTP 502 میگیرید که مستقیم به مشکل اشاره میکند. و چون تابع همهٔ خطاهایش را خودش مدیریت میکند، صدا زدنش بدون await هم دیگر خطری ندارد.
fetch دقیقاً کِی رد میشود؟
روی دیگر سکهٔ نکتهٔ ۴: fetch فقط وقتی رد میشود که درخواست اصلاً به پاسخ نرسد — قطع شبکه، خطای CORS، یا لغو درخواست. در دو حالت اول یک TypeError میگیرید که متنش در هر مرورگر فرق دارد: Chrome میگوید Failed to fetch، Firefox NetworkError when attempting to fetch resource. و Safari Load failed. در گزارشهای کاربران واقعی، این سه را یک خطا حساب کنید، نه سه باگ جدا.
برای تایماوت، راه امروزی AbortSignal.timeout است:
try {
const res = await fetch('/api/orders', { signal: AbortSignal.timeout(10000) });
// ...
} catch (e) {
if (e.name === 'AbortError') return; // لغو عمدی؛ باگ نیست
if (e.name === 'TimeoutError') showError('سرور پاسخ نداد، دوباره تلاش کنید');
report(e);
}
لغو عمدی را — مثلاً وقتی کاربر از صفحه رفته و شما با AbortController درخواست را قطع کردهاید — گزارش نکنید. وگرنه گزارشهایتان پر از خطاهایی میشود که در واقع خطا نیستند.
نکتههای ظریف شنوندهٔ سراسری
reason همیشه Error نیست. هر مقداری میتواند دلیل رد شدن باشد: یک رشته، شیء پاسخ API، یا حتی undefined در Promise.reject(). در این حالتها stack ندارید و گزارش تقریباً بیفایده است. راهحل در مبدأ است: همیشه با new Error(…) رد کنید.
catch دیرهنگام. اگر برای Promise ردشده بعداً — مثلاً در یک تایمر — handler بگذارید، مرورگر اول unhandledrejection را منتشر میکند و بعد رویداد rejectionhandled را. اگر گزارشی دارید که کدش به نظر درست میآید، این حالت را بررسی کنید.
preventDefault پیام کنسول را پنهان میکند. صدا زدن e.preventDefault() در شنونده، چاپ پیشفرض خطا در کنسول را متوقف میکند. فقط وقتی این کار را بکنید که مطمئنید خطا جای دیگری ثبت میشود.
اسکریپتهای شخص ثالث. Promiseهای ردشدهٔ اسکریپتهایی مثل ابزار آمار یا ویجت چت هم به همین شنونده میرسند. با نگاه به stack، آنها را از خطاهای کد خودتان جدا کنید. اگر از باگماگ استفاده میکنید، SDK آن همین رویداد را خودکار گوش میدهد و لازم نیست شنوندهٔ جدا بنویسید.
الگوهایی که مشکل را کم میکنند
- هر تابع async که در پسزمینه صدا زده میشود، catch داشته باشد. اگر
awaitنمیکنید، دستکم.catch(report)بگذارید. res.okرا همیشه بررسی کنید. یا یک تابع کمکی بنویسید که این کار را خودکار کند و همهجا از آن استفاده کنید.- حالت خطا را در رابط کاربری طراحی کنید. هر جایی که اسپینر دارید، باید حالت «نشد» هم داشته باشد — با امکان تلاش دوباره.
- تایماوت بگذارید. درخواستی که هرگز جواب نمیدهد بدتر از درخواستی است که شکست میخورد؛ دستکم با تایماوت تبدیل به خطای قابل مدیریت میشود.
- در catch پیام عمومی ننویسید. «خطای شبکه» وقتی مشکل چیز دیگری است، ساعتها وقت دیباگ میگیرد.
پرسشهای رایج
چرا try/catch دور return fetchUser() خطا را نمیگیرد؟
چون داخل تابع async، return بدون await خود Promise را برمیگرداند و تابع پیش از رد شدن آن از بلوک try خارج میشود. رد شدن به فراخواننده میرسد، نه به catch همین تابع. اگر میخواهید خطا همینجا گرفته شود، return await fetchUser() بنویسید.
فرق .catch() با پارامتر دوم then چیست؟
در p.then(onOk, onFail)، تابع onFail فقط رد شدن خود p را میگیرد، نه خطایی که داخل onOk رخ دهد. .catch() در انتهای زنجیره هر دو را میگیرد.
آیا forEach با تابع async امن است؟
نه. forEach منتظر Promiseها نمیماند، پس await و try/catch بیرونی هیچکدام رد شدنها را نمیبینند و هر کدام مدیریتنشده میماند. بهجایش از for...of با await استفاده کنید، یا برای اجرای موازی از Promise.allSettled.
جمعبندی
این خطا دقیقاً به این دلیل خطرناک است که هیچکس را بیدار نمیکند: صفحه نمیشکند، کاربر شکایت نمیکند، و در لاگ سرور هم چیزی نیست. تنها راه دیدنش گوش دادن به رویداد unhandledrejection و فرستادن آن به جایی است که واقعاً نگاهش میکنید. این یکی از هفت خانوادهای است که در راهنمای جامع خطاهای جاوااسکریپت معرفی کردهایم.
اگر امروز فقط یک کار میخواهید بکنید، همان شنوندهٔ سراسری را اضافه کنید. احتمالاً ظرف چند روز خطاهایی میبینید که ماهها بیصدا اتفاق میافتادهاند.
منابع و مطالعهٔ بیشتر
- رویداد unhandledrejection در MDN — شنوندهٔ سراسری برای Promiseهای ردشده
- استفاده از Promiseها — MDN — زنجیره، catch و خطاهای رایج
- Promise.allSettled در MDN — ادامه دادن با وجود شکست یکی از اعضا
- رویداد unhandledRejection در Node.js — رفتار سمت سرور
باگماگ را رایگان امتحان کنید
خطاهای سایتتان را خودکار ثبت کنید و بگذارید کاربران با یک کلیک باگ گزارش دهند.
شروع رایگان