Window: unhandledrejection イベント

unhandledrejection イベントは、 JavaScript の拒否ハンドラーを持たない Promise が拒否されたときにスクリプトのグローバルスコープに送られます。 通常、これは window ですが、 Worker であることもあります。 これはデバッグや、予期しない場面でのエラーハンドリングのエラーの代替手段を提供するために利用することができます。

バブリング なし
キャンセル 可
インターフェイス PromiseRejectionEvent
イベントハンドラープロパティ onunhandledrejection

使用上のメモ

unhandledrejection イベントにバブリングを許すと、結局はコンソールにエラーメッセージを出力することになります。 これは PromiseRejectionEvent の preventDefault() を呼び出すことで防ぐことができます。 例は以下の Preventing default handling を参照してください。

例

ここで unhandledrejection イベントの使い方が分かる例をいくつか見てみましょう。 イベントには 2 つの有用な情報があります。

promise

拒否を扱うために利用できるハンドラーがなく拒否された実際の Promise です。

reason

拒否ハンドラーに渡されるはずだった理由です。 詳しくは catch() を参照してください。

基本的なエラーのログ

この例では、処理されなかった Promise の拒否についての情報を単純にコンソールにログ出力します。

js

window.addEventListener("unhandledrejection", event => {
  console.warn(`UNHANDLED PROMISE REJECTION: ${event.reason}`);
});

イベントハンドラープロパティを使用して、イベントリスナーを設定することもできます。

js

window.onunhandledrejection = event => {
  console.warn(`UNHANDLED PROMISE REJECTION: ${event.reason}`);
};

既定のハンドリングの防止

(Node.js など) 多くの環境では、既定では処理されなかった Promise の拒否はコンソールに報告されます。 unhandledrejection イベントのハンドラー — と、さらに実行したいその他のタスク — を追加して、 preventDefault() を呼び出すことでイベントをキャンセルし、実行時のログ出力コードが扱われるまでバブリングすることを防ぐことができます。 これは unhandledrejection がキャンセル可能であるためです。

js

window.addEventListener('unhandledrejection', function (event) {
  // ...your code here to handle the unhandled rejection...

  // Prevent the default handling (such as outputting the
  // error to the console

  event.preventDefault();
});

仕様書

Specification
HTML Standard
# event-unhandledrejection
HTML Standard
# handler-window-onunhandledrejection

ブラウザーの互換性

BCD tables only load in the browser

関連情報

[1] 対応するイベントハンドラープロパティは、WindowEventHandlers ミックスインで定義されています。 これは、Window インターフェイスとすべての種類の Worker インターフェイスの両方で使用できます。