Node.jsのUnhandledPromiseRejectionの原因と直し方

​​Node.js​JavaScript,トラブルシュート

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() は、必ず失敗するようにしてあります。

js
// 注文を保存したあと、ログの送信を 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で止まりました。

text
$ 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 を作り、そのまま放っておきます。

js
// Error ではなく文字列で reject する
function loadConfig() {
  return new Promise((resolve, reject) => {
    setTimeout(() => reject('設定ファイルが見つかりません'), 10);
  });
}

loadConfig(); // await も .catch() もしていない
console.log('started');

実行すると、次のように出て終了コード1で止まりました。

text
$ 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)。

text
$ 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() を付けて、失敗をそこで受け止めます。

js
// 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);
text
$ node fix-catch.mjs
saved: 42
log failed: ログを送れませんでした(注文 42)
done

エラーは出なくなり、最後の done まで動いて、終了コードは0になりました。saved: 42 が先に出ているので、ログの送信を待たずに先へ進んでいることも分かります。

直し方2:待つ処理は await して try〜catch で囲む

ログの送信が終わってから先へ進みたいなら、await を付けて、try〜catch で囲みます。

js
async function saveOrder(orderId) {
  try {
    await sendLog(orderId);
  } catch (err) {
    console.error('log failed:', err.message);
  }
  console.log('saved:', orderId);
}
text
$ node fix-await.mjs
log failed: ログを送れませんでした(注文 42)
saved: 42
done

こちらも終了コード0で最後まで動きました。今度は、ログの送信が終わって(失敗して)から saved: 42 が出ています。sendLog() と saveOrder(42) の呼び出しは、前の例と同じです。

文字列で失敗していた reject-string.mjs も、Error で失敗するように変え、loadConfig() に .catch() を付けました。

js
// 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)で分かります。

text
$ node reject-string-fixed.mjs
started
config error: 設定ファイルが見つかりません

await していても止まる書き方

await を書いているのに止まることもあります。検証で止まったのは、次の2つの書き方です。

先に始めた Promise を、あとから await する

2つの読み込みを同時に始めて、あとから1つずつ await する書き方です。全体を try〜catch で囲んでいます。

js
// 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で止まりました。

text
$ 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() でまとめて待ちます。

js
try {
  const [user, posts] = await Promise.all([loadUser(), loadPosts()]);
  console.log(user, posts);
} catch (err) {
  console.error('caught:', err.message);
}
text
$ node late-await-fixed.mjs
caught: 投稿を読み込めませんでした

今度は catch で受け止められ、終了コード0で終わりました。Promise.all() は、渡された Promise のどれかが失敗した時点で、最初の失敗の理由で失敗します。全部の結果がそろうまで待ちたいときは、Promise.allSettled() を使います。

forEach に async 関数を渡す

配列の要素ごとに非同期の処理をするとき、forEach に async 関数を渡すと、try〜catch で囲んでいても失敗を受け止められません。

js
// 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);
}
text
$ 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 します。

js
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);
}
text
$ 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にします。

js
// 取りこぼしを記録して、終了コード 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);
text
$ node handler.mjs
unhandledRejection: ログを送れませんでした(注文 42)
この行も表示される

失敗のあとも処理が続き、この行も表示される が出て、終了コード1で終わりました。ただし、これは失敗した処理を直したわけではありません。どの Promise がどこで失敗したかをここで記録しておき、見つかった箇所を直し方1・2のように書き直すための手がかりにします。

注意

起動オプションの --unhandled-rejections=warn を付けると、Node.js 15 より前と同じく警告を出すだけになります。検証では、fire-and-forget.mjs が UnhandledPromiseRejectionWarning を出したあとも動き続け、終了コードは0でした。失敗が起きても終了コードでは分からなくなるので、エラーを消す目的で付けるのは避けてください。

​Posted by 86