Node.jsのUnhandledPromiseRejectionの原因と直し方
Node.js で、await も .catch() もしていない Promise が失敗すると、プロセスはその場で終了コード1で止まります。Error ではない値で失敗したときは、UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block... というメッセージが出ます。失敗を .catch() か try〜catch で受け止めると、このエラーは消え、プロセスも止まらなくなります。
ログの送信やメールの通知を「待たずに投げておく」書き方をした API サーバーやバッチ処理で、プロセスが止まる原因になるエラーです。私は検証環境でこのエラーを起こし、出たメッセージを写したうえで、直すと消えることを確かめました。
検証環境は Ubuntu 24.04 で、Node.js 24.22.1 と 22.23.4 を使いました。どちらもメッセージは同じで、違ったのは Node.js の内部の行(node:internal/… の行番号や関数名)と、最後のバージョンの行だけです。以下の出力は Node.js 24 のもので、作業フォルダのパスは /path/to/app に置き換え、Node.js の実行ファイルの場所は省いて node と書いています。Windows と macOS での動きは試していません。ブラウザーのコンソールに出る Uncaught (in promise) は、別の記事「JavaScriptのUncaught (in promise)の原因と直し方」で扱っています。
await していない Promise が失敗すると止まる
次の fire-and-forget.mjs は、注文を保存したあと、ログの送信 sendLog() を await せずに始めます。sendLog() は、必ず失敗するようにしてあります。
// 注文を保存したあと、ログの送信を await せずに始める
async function sendLog(orderId) {
throw new Error(`ログを送れませんでした(注文 ${orderId})`);
}
async function saveOrder(orderId) {
sendLog(orderId); // await していない
console.log('saved:', orderId);
}
await saveOrder(42);
setTimeout(() => console.log('この行は表示されない'), 100);
実行すると、saved: 42 のあとに次のエラーが出て、終了コード1で止まりました。
$ node fire-and-forget.mjs
saved: 42
file:///path/to/app/fire-and-forget.mjs:3
throw new Error(`ログを送れませんでした(注文 ${orderId})`);
^
Error: ログを送れませんでした(注文 42)
at sendLog (file:///path/to/app/fire-and-forget.mjs:3:9)
at saveOrder (file:///path/to/app/fire-and-forget.mjs:7:3)
at file:///path/to/app/fire-and-forget.mjs:11:7
at ModuleJob.run (node:internal/modules/esm/module_job:561:25)
at async node:internal/modules/esm/loader:647:26
at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)
Node.js v24.22.1
100ミリ秒後に出す予定だった この行は表示されない は、出ていません。sendLog() の失敗を誰も受け止めなかったので、Node.js はプロセスを止めました。
このように、Error で失敗したときは、メッセージに「UnhandledPromiseRejection」という言葉は出ず、ふつうの例外と同じ形で表示されます。スタックトレースの先頭には、失敗した関数(ここでは sendLog)の場所が出ます。
Error ではない値で失敗すると UnhandledPromiseRejection と出る
reject() に Error ではなく文字列を渡すと、表示が変わります。次の reject-string.mjs は、10ミリ秒後に文字列で失敗する Promise を作り、そのまま放っておきます。
// Error ではなく文字列で reject する
function loadConfig() {
return new Promise((resolve, reject) => {
setTimeout(() => reject('設定ファイルが見つかりません'), 10);
});
}
loadConfig(); // await も .catch() もしていない
console.log('started');
実行すると、次のように出て終了コード1で止まりました。
$ node reject-string.mjs
started
node:internal/process/promises:392
new UnhandledPromiseRejection(reason);
^
UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "設定ファイルが見つかりません".
at throwUnhandledRejectionsMode (node:internal/process/promises:392:7)
at processPromiseRejections (node:internal/process/promises:475:17)
at process.processTicksAndRejections (node:internal/process/task_queues:106:37) {
code: 'ERR_UNHANDLED_REJECTION'
}
Node.js v24.22.1
英語のメッセージは「async 関数の中で catch のないまま例外を投げたか、.catch() で処理していない Promise を reject したことが原因です」という意味です。最後の The promise rejected with the reason "…" に、reject() に渡した文字列がそのまま入ります。
困るのは、スタックトレースが Node.js の内部(node:internal/…)だけで、自分のコードのどこで失敗したのかが出ないことです。同じコードで、reject() に new Error('設定ファイルが見つかりません') を渡すように変えると、受け止めていないことは同じでも、reject() を書いた行が出るようになりました(終了コードは同じく1)。
$ node reject-error.mjs
started
file:///path/to/app/reject-error.mjs:4
setTimeout(() => reject(new Error('設定ファイルが見つかりません')), 10);
^
Error: 設定ファイルが見つかりません
at Timeout._onTimeout (file:///path/to/app/reject-error.mjs:4:29)
at listOnTimeout (node:internal/timers:685:17)
at process.processTimers (node:internal/timers:618:7)
Node.js v24.22.1
reject() や throw には、文字列ではなく Error を渡しておくと、失敗した場所を探しやすくなります。
この止まり方は、Node.js 15 からの既定の動きです。Node.js のコマンドラインオプションの説明にある --unhandled-rejections では、既定のモードが throw で、unhandledRejection イベントを登録していなければ、受け止められなかった失敗を「捕まえられなかった例外」として扱うと書かれています。Node.js 15 より前は、警告を出すだけでした。
直し方1:待たない処理には .catch() を付ける
ログの送信のように、終わるのを待たずに先へ進みたい処理は、await しないままで構いません。そのかわり、呼び出したところで .catch() を付けて、失敗をそこで受け止めます。
// await しないまま、.catch() で失敗を受け止める
async function sendLog(orderId) {
throw new Error(`ログを送れませんでした(注文 ${orderId})`);
}
async function saveOrder(orderId) {
sendLog(orderId).catch((err) => {
console.error('log failed:', err.message);
});
console.log('saved:', orderId);
}
await saveOrder(42);
setTimeout(() => console.log('done'), 100);
$ node fix-catch.mjs
saved: 42
log failed: ログを送れませんでした(注文 42)
done
エラーは出なくなり、最後の done まで動いて、終了コードは0になりました。saved: 42 が先に出ているので、ログの送信を待たずに先へ進んでいることも分かります。
直し方2:待つ処理は await して try〜catch で囲む
ログの送信が終わってから先へ進みたいなら、await を付けて、try〜catch で囲みます。
async function saveOrder(orderId) {
try {
await sendLog(orderId);
} catch (err) {
console.error('log failed:', err.message);
}
console.log('saved:', orderId);
}
$ node fix-await.mjs
log failed: ログを送れませんでした(注文 42)
saved: 42
done
こちらも終了コード0で最後まで動きました。今度は、ログの送信が終わって(失敗して)から saved: 42 が出ています。sendLog() と saveOrder(42) の呼び出しは、前の例と同じです。
文字列で失敗していた reject-string.mjs も、Error で失敗するように変え、loadConfig() に .catch() を付けました。
// Error で reject し、呼び出す側で .catch() を付ける
function loadConfig() {
return new Promise((resolve, reject) => {
setTimeout(() => reject(new Error('設定ファイルが見つかりません')), 10);
});
}
loadConfig().catch((err) => {
console.error('config error:', err.message);
process.exitCode = 1;
});
console.log('started');
実行すると、UnhandledPromiseRejection は出なくなりました。.catch() の中で process.exitCode = 1 を設定したので、失敗したことは終了コード(1)で分かります。
$ node reject-string-fixed.mjs
started
config error: 設定ファイルが見つかりません
await していても止まる書き方
await を書いているのに止まることもあります。検証で止まったのは、次の2つの書き方です。
先に始めた Promise を、あとから await する
2つの読み込みを同時に始めて、あとから1つずつ await する書き方です。全体を try〜catch で囲んでいます。
// 2つの読み込みを先に始めて、あとから順に await する
const wait = (ms) => new Promise((r) => setTimeout(r, ms));
async function loadUser() {
await wait(200);
return { name: 'neko' };
}
async function loadPosts() {
await wait(50);
throw new Error('投稿を読み込めませんでした');
}
try {
const userPromise = loadUser();
const postsPromise = loadPosts();
const user = await userPromise; // ここで 200ms 待つあいだに、postsPromise が失敗する
const posts = await postsPromise;
console.log(user, posts);
} catch (err) {
console.error('caught:', err.message);
}
実行すると、catch の caught: は出ず、終了コード1で止まりました。
$ node late-await.mjs
file:///path/to/app/late-await.mjs:10
throw new Error('投稿を読み込めませんでした');
^
Error: 投稿を読み込めませんでした
at loadPosts (file:///path/to/app/late-await.mjs:10:9)
Node.js v24.22.1
loadPosts() は50ミリ秒で失敗しますが、そのときプログラムは await userPromise で200ミリ秒待っている最中です。postsPromise にはまだ誰も await も .catch() もしていないので、Node.js は受け止められなかった失敗とみなします。process の 'unhandledRejection' イベントの説明にも、イベントループの1回のうちに .catch() などのエラー処理が付けられなかった失敗が対象になると書かれています。あとで await する予定があっても、間に合いません。
同時に始めた Promise は、Promise.all() でまとめて待ちます。
try {
const [user, posts] = await Promise.all([loadUser(), loadPosts()]);
console.log(user, posts);
} catch (err) {
console.error('caught:', err.message);
}
$ node late-await-fixed.mjs
caught: 投稿を読み込めませんでした
今度は catch で受け止められ、終了コード0で終わりました。Promise.all() は、渡された Promise のどれかが失敗した時点で、最初の失敗の理由で失敗します。全部の結果がそろうまで待ちたいときは、Promise.allSettled() を使います。
forEach に async 関数を渡す
配列の要素ごとに非同期の処理をするとき、forEach に async 関数を渡すと、try〜catch で囲んでいても失敗を受け止められません。
// forEach に async 関数を渡す
async function upload(name) {
if (name === 'b.txt') throw new Error(`アップロードに失敗しました: ${name}`);
return name;
}
try {
['a.txt', 'b.txt', 'c.txt'].forEach(async (name) => {
await upload(name);
console.log('uploaded:', name);
});
console.log('all done');
} catch (err) {
console.error('caught:', err.message);
}
$ node foreach.mjs
all done
uploaded: a.txt
uploaded: c.txt
file:///path/to/app/foreach.mjs:3
if (name === 'b.txt') throw new Error(`アップロードに失敗しました: ${name}`);
^
Error: アップロードに失敗しました: b.txt
at upload (file:///path/to/app/foreach.mjs:3:31)
at file:///path/to/app/foreach.mjs:9:11
at Array.forEach (<anonymous>)
at file:///path/to/app/foreach.mjs:8:31
at ModuleJob.run (node:internal/modules/esm/module_job:561:25)
at async node:internal/modules/esm/loader:647:26
at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)
Node.js v24.22.1
アップロードが終わる前に all done が出て、そのあと終了コード1で止まりました。MDN の forEach の説明にあるとおり、forEach は渡した関数が返す Promise を待ちません。async 関数が返した Promise は、そのまま捨てられます。
1つずつ順番に処理するなら、for...of の中で await します。
try {
for (const name of ['a.txt', 'b.txt', 'c.txt']) {
await upload(name);
console.log('uploaded:', name);
}
console.log('all done');
} catch (err) {
console.error('caught:', err.message);
}
$ node foreach-fixed.mjs
uploaded: a.txt
caught: アップロードに失敗しました: b.txt
b.txt の失敗が catch に届き、終了コード0で終わりました。失敗したところで止まるので、c.txt には進んでいません。同時に処理したいときは、await Promise.all(names.map((name) => upload(name))) のように、map で作った Promise の配列を Promise.all() で待ちます。検証では、この書き方でも b.txt の失敗が catch に届き、caught: アップロードに失敗しました: b.txt と出て終了コード0で終わりました。
unhandledRejection イベントは取りこぼしの記録に使う
process.on('unhandledRejection', …) を登録すると、受け止められなかった失敗があっても、プロセスはその場では止まらなくなります。次の handler.mjs は、失敗の内容を出して、終了コードを1にします。
// 取りこぼしを記録して、終了コード 1 で終わる
process.on('unhandledRejection', (reason) => {
console.error('unhandledRejection:', reason instanceof Error ? reason.message : reason);
process.exitCode = 1;
});
async function sendLog(orderId) {
throw new Error(`ログを送れませんでした(注文 ${orderId})`);
}
sendLog(42);
setTimeout(() => console.log('この行も表示される'), 100);
$ node handler.mjs
unhandledRejection: ログを送れませんでした(注文 42)
この行も表示される
失敗のあとも処理が続き、この行も表示される が出て、終了コード1で終わりました。ただし、これは失敗した処理を直したわけではありません。どの Promise がどこで失敗したかをここで記録しておき、見つかった箇所を直し方1・2のように書き直すための手がかりにします。
起動オプションの --unhandled-rejections=warn を付けると、Node.js 15 より前と同じく警告を出すだけになります。検証では、fire-and-forget.mjs が UnhandledPromiseRejectionWarning を出したあとも動き続け、終了コードは0でした。失敗が起きても終了コードでは分からなくなるので、エラーを消す目的で付けるのは避けてください。




