「Failed to Fetch Dynamically Imported Module」エラーの解決方法
ViteのFailed to fetch dynamically imported moduleエラーを解決。バージョン不整合、誤ったパス、HTML応答、ネットワーク障害を特定し、旧アセットの保持と安全な再読み込みを設定します。
「Failed to fetch dynamically imported module」は、import() で要求された JavaScript チャンクをブラウザが読み込めなかったことを示すエラーです。本番環境では、すでに開かれているタブが必要とするチャンクを新しいデプロイが削除してしまったことが、主な原因です。
よくあるパターンはこうです。リリースを出した数分後にエラートラッカーが一斉に反応し始めますが、自分でルートを一通りクリックしてみても問題なく動作します。新しいビルド自体は壊れていません。失敗しているリクエストは、前のビルドを読み込んだタブから送られています。
この記事では、デプロイ時に何が起きているのか、段階的に積み重ねていく 3 つの対策(アセットの保持、リロードハンドラー、ループガード)、同じメッセージを引き起こすあまり一般的でない原因、そしてそれらを見分けるための Network タブの判別表を解説します。
重要なポイント
- 「Failed to fetch dynamically imported module」の最も一般的な原因はバージョンスキューです。前回のデプロイ時に開かれたタブが、サーバー上にもう存在しないハッシュ付きファイル名で遅延チャンクを要求してしまいます。
index.htmlをCache-Control: no-cacheで配信し、前回デプロイのアセットを利用可能なまま残しておけば、クライアント側のコードを実行するまでもなく、スキューによる失敗の大半を防げます。- Vite の
vite:preloadErrorイベントを使うと、チャンクの読み込みに失敗した際にページをリロードできます。ただし、無限にリロードし続けないよう、ハンドラーには sessionStorage のタイムスタンプによるガードが必要です。 - 失敗している
.jsリクエストが 200 とContent-Type: text/htmlを返している場合、それはバージョンスキューではなく、サーバーまたは CDN のフォールバックの問題です。 - 失敗した動的インポートをリトライしても、バージョンスキューは解決できません。古いビルドが参照しているファイルはすでに存在しないためです。
なぜデプロイによって開いているタブが壊れるのか?
Vite のトラブルシューティングガイドでは、TypeError: Failed to fetch dynamically imported module の原因として、バージョンスキュー、不安定なネットワーク環境、リクエストをブロックするブラウザ拡張機能の 3 つを挙げています。このうち、リリース後に急増するのはバージョンスキューです。
流れは次のとおりです。ユーザーがビルド A の index.html を読み込みます。このファイルは assets/Settings-a1b2c3.js のようなチャンクを参照しています。その後ビルド B をデプロイすると、コンテンツハッシュが変わります。ユーザーのタブではまだビルド A が動いています。ユーザーが遅延ロードされるルートに遷移すると、ブラウザは Settings-a1b2c3.js を要求して 404 を受け取り、インポートが reject されます。
TypeError: Failed to fetch dynamically imported module: https://example.com/assets/Settings-a1b2c3.js
これは Chromium での文言です。同じ失敗でも他のブラウザでは表現が異なるため、トラッカーでは正確な文字列ではなく原因ごとにグループ化してください。
この問題をローカルで再現できることはまずありません。新たにページを読み込めば、HTML とチャンクは常に同じビルドから取得されるからです。失敗が起きるのは、デプロイ前に古いビルドを読み込み、デプロイ後に遅延ルートを要求したタブだけです。また、このエラーは Vite の「Failed to resolve import」エラーとは無関係です。あちらはビルド時の解決エラーであり、こちらはランタイムで発生するエラーです。
対策 1:古いアセットを保持し、HTML を再検証させる
バージョンスキューに対する最も低コストな対策はサーバー側で行います。前のビルドのチャンクを利用可能なまま残し、HTML を Cache-Control: no-cache で配信するのです。ビルド B をリリースした後もビルド A のチャンクが残っていれば、古いタブは動作し続けます。Vite の読み込みエラーの処理に関する説明でも、多くのホスティング環境が前回デプロイのアセットを削除してしまうことが指摘されており、HTML に Cache-Control: no-cache を付けることが推奨されています。
index.html を Cache-Control: no-cache で配信すると、ブラウザは読み込みのたびに HTML を再検証します。その結果、リロード時には削除されたチャンク名ではなく、新しいビルドのチャンク名が取得されます。ハッシュ付きアセットはその逆です。内容が変わるたびに URL も変わるため、長い max-age と MDN で解説されている immutable ディレクティブを安全に使用できます。
location = /index.html {
add_header Cache-Control "no-cache";
}
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
try_files $uri =404;
}
location / {
try_files $uri $uri/ /index.html;
}
デプロイは追加型にしましょう。新しい assets/ を古いファイルと並べてアップロードし、古いファイルは定期的に削除します。どのくらいの期間保持するかは判断次第ですが、ユーザーが現実的に開いたままにしているタブよりも長く残る程度の期間にしてください。
対策 2:vite:preloadError で一度だけリロードする
クライアント側では、動的インポートの読み込みに失敗すると Vite が window 上で vite:preloadError イベントを発火します。このハンドラーからページをリロードすれば、バージョンスキューから復旧できます。サーバー側でアセットを保持しても、古いチャンクはいずれ削除されます。元のエラーは event.payload に格納されており、event.preventDefault() を呼び出すと Vite はそのエラーをスローしなくなります。ビルドガイドでは、このハンドラーからページをリロードすることが提案されています。
リロードすると現在の index.html が取得され、そこではビルド B のチャンクが参照されています。これでバージョンスキューは解消されます。一方、インポートをリトライしても解決しません。ビルド A が指しているファイルは、もうサーバー上に存在しないからです。効果があるのは新しい HTML を読み込むことだけです。(その場でのリトライが役立つのは、一時的なネットワーク障害の場合に限られます。かつて HTML 仕様では失敗したモジュールの取得結果がキャッシュされていましたが、whatwg/html#10327 でこの挙動が変更されました。対応状況は MDN の import() 互換性一覧表のとおり、ブラウザによって異なります。)
対策 3:リロードループを防止する
vite:preloadError のリロードハンドラーには、リロードループを防ぐガードが必要です。たとえばエッジキャッシュが no-cache を無視するなどして HTML 自体が古い場合や、チャンクがどちらのビルドにも存在しない場合、リロードしても同じように失敗し、ページが延々とリロードされ続けます。この復旧処理を標準で備えているフレームワークもあるので、まずは使用しているフレームワークのドキュメントを確認してください。たとえば Nuxt はデフォルトでチャンク読み込みエラー時にリロードします。そのリロードヘルパーは各リロードを sessionStorage に記録し、10 秒間は繰り返しのリクエストを無視します。React、Vue、Svelte を素の Vite で使っている場合は、エントリーファイルに次のコードを追加します。
// src/main.js
const RELOAD_KEY = 'chunk-reload-at';
const RELOAD_WINDOW_MS = 10_000; // tunable, not a standard value
function lastReload() {
try {
return Number(sessionStorage.getItem(RELOAD_KEY)) || 0;
} catch {
return 0;
}
}
function markReload() {
try {
sessionStorage.setItem(RELOAD_KEY, String(Date.now()));
return true;
} catch {
return false; // storage unavailable: don't risk a loop
}
}
window.addEventListener('vite:preloadError', (event) => {
console.error(event.payload); // send to your error tracker instead
const recentlyReloaded = Date.now() - lastReload() < RELOAD_WINDOW_MS;
if (!recentlyReloaded && markReload()) {
event.preventDefault();
window.location.reload();
}
// Otherwise let the error reach the app's error boundary.
});
このハンドラーは即座にリロードするため、preventDefault() 後にインポートが何に解決されるかには依存しません。指定期間内にすでにリロードが行われている場合、ハンドラーはエラーを抑制しません。エラーは伝播し、Error Boundary が代わりにメッセージを表示します。
import React from 'react';
class ChunkErrorBoundary extends React.Component {
state = { failed: false };
static getDerivedStateFromError() {
return { failed: true };
}
render() {
if (!this.state.failed) return this.props.children;
return (
<div role="alert">
<p>A new version is available.</p>
<button onClick={() => window.location.reload()}>Refresh</button>
</div>
);
}
}
Refresh ボタンはユーザー自身の操作によるものなので、ガードでブロックする必要はありません。Vue や Svelte にも同等のエラーハンドリング用フックがあります。いずれにしても、reject はルートまたは Error Boundary のレベルで処理してください。失敗したすべての動的インポートがこのイベントを経由するかどうかは、Vite のドキュメントで明記されていないためです。
同じエラーを引き起こす、あまり一般的でない原因
「Failed to fetch dynamically imported module」は、デプロイとは無関係なパス、サーバー、クライアントの問題によっても発生します。こうした失敗は通常、リリース後に開始されたセッションにも影響します。
-
baseパスの誤り。 失敗しているチャンクの URL に、アプリのデプロイ先のパスプレフィックスが含まれていない場合、原因は古いデプロイではなく Vite 設定のbaseオプションです。Vite の public base path に関するドキュメントにあるとおり、デプロイ先のパスに合わせて設定するか、ビルド時に--baseを指定してください。// vite.config.js — app served from https://example.com/app/ // without base: /assets/c-x1y2.js (404) // with base: /app/assets/c-x1y2.js import { defineConfig } from 'vite'; export default defineConfig({ base: '/app/' }); -
.jsの URL に対して HTML が返される。 SPA のフォールバックや CDN のリライトが、不明なチャンクパスに対してindex.htmlを返してしまうケースです。この場合、MIME タイプが JavaScript ではないため、ブラウザはそのレスポンスをモジュールとして拒否します。上記の nginx 設定のように/assets/をフォールバックの対象から除外し、存在しないファイルには正しく 404 を返すようにしてください。 -
広告ブロッカー。 拡張機能は、ファイル名に「ad」や「track」といった語を含むファイルをブロックすることがよくあります。Vite は
build.rolldownOptions.output.chunkFileNamesでチャンク名を変更することを推奨しています。Vite 7 以前ではこのオプションはbuild.rollupOptionsで、Vite 8 でも非推奨のエイリアスとして引き続き使用できます。build: { rolldownOptions: { output: { chunkFileNames: 'assets/c-[hash].js' } } } -
ネットワークの切断。 断続的に発生し、ファイル名を問わず起こり、HTTP ステータスはありません。これもガード付きリロードで対処できます。
原因をどう見分けるか?
Network タブを開いて失敗しているチャンクのリクエストを探し、ステータスコードと Content-Type の 2 点を確認します。この 2 つを組み合わせれば原因を特定できます。
| 失敗しているチャンクリクエストの状態 | 考えられる原因 | 対策 |
|---|---|---|
| 404、古いビルドのハッシュ付きファイル名 | バージョンスキュー | 対策 1〜3 |
200、Content-Type: text/html | SPA フォールバックまたは CDN リライト | /assets/ 配下で正しく 404 を返す |
| 404、URL にデプロイ先のサブパスがない | base の誤り | base を設定する |
| ブロック、ファイル名に広告関連の語を含む | 拡張機能 | chunkFileNames で名前を変更する |
| ステータスなしで失敗、断続的に発生 | ネットワーク | ガード付きリロード |
通常、この失敗を自分で再現することはできないため、どのケースに該当するかは本番環境のデータから判断する必要があります。しっかりとしたエラーロギングのプラクティスの一環として、各エラーにリリース識別子を記録しましょう。エラートラッキングとセッションリプレイを組み合わせれば、デプロイ前に開始されたセッションで、デプロイ直後に失敗が集中しているかどうかがわかります。これがスキューの特徴です。リプレイでは、ガードが一度だけリロードして復旧できたかどうかも確認できます。「ResizeObserver loop completed」エラーと同様、これはノイズの多い本番エラーですが、ミュートするのではなく分類すべきものです。
根本原因を解決する
「Failed to fetch dynamically imported module」は、多くの場合、デプロイの問題がクライアントコードに表面化したものです。まずはサーバー側から対処しましょう。以前のアセットを保持し、index.html を no-cache で配信し、/assets/ が決して HTML にフォールバックしないようにします。そのうえで、安全策としてガード付きの vite:preloadError ハンドラーと Error Boundary を追加します。設定を変更する前に、Network タブで失敗しているリクエストを開き、ステータスコードとコンテンツタイプから原因を確認してください。
よくある質問
これは webpack の ChunkLoadError と同じ問題ですか?
はい、根本原因は同じですが、エラーの発生源が異なります。webpack は独自のランタイムでチャンクを読み込むため、ChunkLoadError と「Loading chunk 42 failed」のようなメッセージで reject されます。Vite の本番ビルドはネイティブの import() を使用するため、ブラウザ自身のエラーが表示されます。サーバー側の対策はどちらも同じで、古いアセットを保持し、HTML を再検証させることです。なお、vite:preloadError イベントは Vite にのみ存在します。
Service Worker やチャンクのプリフェッチでバージョンスキューのエラーを防げますか?
どちらも Vite のトラブルシューティングガイドで緩和策として挙げられています。すべてのアセットをプリフェッチしてキャッシュする Service Worker を使えば、サーバーが古いビルドのチャンクを削除した後でも、すでに開かれているタブはそれらを利用できます。動的チャンクのプリフェッチは、デプロイによって削除される前にチャンクを読み込んでおく方法ですが、Cache-Control ヘッダーの設定によってブラウザが HTML をキャッシュしている場合には効果がありません。
デプロイがない Vite 開発サーバーで、なぜこのエラーが発生するのですか?
開発サーバーでの主な原因はブラウザ拡張機能です。Vite のトラブルシューティングガイドによると、広告ブロッカーなどの拡張機能が Vite クライアントから開発サーバーへのリクエストを妨げることがあり、それによって同じエラーメッセージが表示されます。確認するには、localhost で拡張機能を無効にするか、クリーンなブラウザプロファイルでテストしてください。開発環境では、開いているタブの裏でビルドが置き換えられることはないため、バージョンスキューは発生しません。
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k