Corriger l'erreur « Failed to Fetch Dynamically Imported Module »
Corrigez les erreurs Vite Failed to fetch dynamically imported module. Identifiez les versions désynchronisées, chemins incorrects, réponses HTML et problèmes réseau, puis gardez les anciens fichiers et rechargez sans boucle.
L’erreur « Failed to fetch dynamically imported module » signifie que le navigateur n’a pas pu charger un chunk JavaScript demandé via import(). En production, la cause habituelle est la suivante : un nouveau déploiement a supprimé un chunk qu’un onglet déjà ouvert s’attend encore à trouver.
Le scénario est bien connu. Vous publiez une release, l’outil de suivi des erreurs s’affole dans les minutes qui suivent, et pourtant toutes les routes fonctionnent lorsque vous les parcourez vous-même. Rien n’est cassé dans le nouveau build. Les requêtes en échec proviennent d’onglets qui ont chargé le build précédent.
Cet article présente le mécanisme en jeu au moment du déploiement, trois correctifs complémentaires (conservation des assets, gestionnaire de rechargement et garde anti-boucle), les causes moins fréquentes qui produisent le même message, ainsi qu’un tableau d’analyse de l’onglet Réseau permettant de les distinguer.
Points clés
- La cause la plus fréquente de l’erreur « Failed to fetch dynamically imported module » est le décalage de versions (version skew) : un onglet ouvert issu du déploiement précédent demande un chunk chargé à la demande (lazy) via un nom de fichier hashé qui n’existe plus sur le serveur.
- Servir
index.htmlavecCache-Control: no-cacheet conserver les assets du déploiement précédent permet d’éviter la plupart des échecs liés au décalage de versions, avant même l’exécution du moindre code côté client. - L’événement
vite:preloadErrorde Vite permet de recharger la page lorsque le chargement d’un chunk échoue, mais le gestionnaire doit s’appuyer sur un horodatage stocké dans sessionStorage pour éviter un rechargement en boucle. - Une requête
.jsen échec qui renvoie un code 200 avecContent-Type: text/htmlrelève d’un problème de fallback côté serveur ou CDN, et non d’un décalage de versions. - Relancer un import dynamique en échec ne peut pas corriger un décalage de versions, car le fichier référencé par l’ancien build a disparu.
Pourquoi un déploiement casse-t-il les onglets ouverts ?
Le guide de dépannage de Vite recense trois causes à l’erreur TypeError: Failed to fetch dynamically imported module : le décalage de versions, une mauvaise qualité réseau et des extensions de navigateur qui bloquent les requêtes. C’est le décalage de versions qui provoque un pic d’erreurs après une release.
Voici la séquence. Un utilisateur charge le fichier index.html du build A, qui référence des chunks tels que assets/Settings-a1b2c3.js. Vous déployez le build B, et les hashs de contenu changent. L’onglet de l’utilisateur exécute toujours le build A. Lorsqu’il navigue vers une route chargée à la demande, le navigateur demande Settings-a1b2c3.js, reçoit une 404, et l’import est rejeté :
TypeError: Failed to fetch dynamically imported module: https://example.com/assets/Settings-a1b2c3.js
Il s’agit du libellé de Chromium. Les autres navigateurs formulent le même échec différemment : regroupez donc les erreurs par cause dans votre outil de suivi, et non par chaîne exacte.
Il est rarement possible de reproduire le problème en local, car un chargement de page neuf récupère toujours le HTML et les chunks d’un même build. L’échec ne se produit que dans un onglet ayant chargé l’ancien build avant le déploiement et ayant demandé une route lazy après celui-ci. Cette erreur n’a par ailleurs aucun rapport avec l’erreur « Failed to resolve import » de Vite. Cette dernière est un échec de résolution au moment du build, alors que celle qui nous intéresse survient à l’exécution.
Correctif 1 : conserver les anciens assets et revalider le HTML
Le correctif le moins coûteux contre le décalage de versions se situe côté serveur : conserver les chunks du build précédent et servir le HTML avec Cache-Control: no-cache. Si les chunks du build A existent toujours après la mise en ligne du build B, les anciens onglets continuent de fonctionner. Les notes de Vite sur la gestion des erreurs de chargement soulignent que de nombreux hébergements suppriment les assets du déploiement précédent, et recommandent d’appliquer Cache-Control: no-cache au HTML.
Servir index.html avec Cache-Control: no-cache oblige le navigateur à revalider le HTML à chaque chargement. Un rechargement récupère alors les noms de chunks du nouveau build au lieu de ceux qui ont été supprimés. Les assets hashés constituent le cas inverse : leur URL change dès que leur contenu change, ils peuvent donc utiliser sans risque un max-age long avec la directive immutable décrite sur MDN.
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;
}
Rendez vos déploiements additifs : téléversez le nouveau dossier assets/ à côté de l’ancien, puis purgez les anciens fichiers de façon planifiée. La durée de conservation relève de l’appréciation de chacun : elle doit être suffisante pour couvrir la durée de vie réaliste des onglets que vos utilisateurs laissent ouverts.
Correctif 2 : recharger une fois sur vite:preloadError
Côté client, Vite déclenche un événement vite:preloadError sur window lorsque le chargement d’un import dynamique échoue, et recharger la page depuis ce gestionnaire permet de se remettre d’un décalage de versions. La conservation côté serveur aide, mais les anciens chunks finissent tôt ou tard par être purgés. L’erreur d’origine se trouve dans event.payload, et l’appel à event.preventDefault() empêche Vite de la lever. Le guide de build suggère de recharger la page depuis ce gestionnaire.
Un rechargement récupère le fichier index.html actuel, qui référence les chunks du build B. Cela corrige le décalage de versions. Relancer l’import, en revanche, n’y change rien, car le fichier vers lequel pointe le build A n’existe plus sur le serveur : seul le chargement du nouveau HTML est efficace. (Relancer l’import sur place n’est utile qu’en cas de défaillance réseau passagère. La spécification HTML mettait autrefois en cache les échecs de récupération de modules ; whatwg/html#10327 a modifié ce comportement, et la prise en charge varie, comme le montre le tableau de compatibilité de import() sur MDN.)
Correctif 3 : se prémunir contre les boucles de rechargement
Un gestionnaire de rechargement sur vite:preloadError doit être protégé contre les boucles de rechargement. Si le HTML lui-même est obsolète, par exemple parce qu’un cache edge ignore no-cache, ou si le chunk est absent des deux builds, le rechargement échoue de la même manière et la page se recharge indéfiniment. Certains frameworks intègrent ce mécanisme de récupération : consultez d’abord la documentation du vôtre. Nuxt, par exemple, recharge la page par défaut en cas d’erreur de chargement de chunk, et son utilitaire de rechargement enregistre chaque rechargement dans sessionStorage puis ignore les demandes répétées pendant 10 secondes. Pour Vite seul avec React, Vue ou Svelte, ajoutez ce code à votre fichier d’entrée :
// 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.
});
Le gestionnaire recharge immédiatement la page, si bien que rien ne dépend de la valeur à laquelle l’import se résout après preventDefault(). Si un rechargement a déjà eu lieu dans la fenêtre définie, le gestionnaire ne neutralise pas l’erreur. Celle-ci se propage, et une error boundary affiche un message à la place :
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>
);
}
}
Le bouton Refresh étant déclenché par l’utilisateur, la garde n’a pas besoin de le bloquer. Vue et Svelte disposent de hooks de gestion d’erreurs équivalents. Dans tous les cas, traitez le rejet au niveau de la route ou de la boundary, car la documentation de Vite ne précise pas si chaque import dynamique en échec passe par cet événement.
Causes moins fréquentes de la même erreur
L’erreur « Failed to fetch dynamically imported module » peut aussi provenir de problèmes de chemin, de serveur ou de client sans aucun lien avec les déploiements. Ces échecs touchent généralement aussi les sessions ouvertes après la release.
-
Mauvais chemin
base. Si l’URL du chunk en échec ne comporte pas le préfixe de chemin sous lequel l’application est déployée, la cause est l’optionbasede la configuration Vite, et non un déploiement obsolète. Définissez-la de façon à correspondre au chemin de déploiement, ou passez--baseau moment du build, comme l’explique la documentation de Vite sur le chemin de base public :// 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/' }); -
HTML servi pour une URL
.js. Un fallback de SPA ou une règle de réécriture du CDN répond à la demande de chunk inconnue en renvoyantindex.html. Le navigateur rejette alors la réponse en tant que module, car son type MIME n’est pas JavaScript. Excluez/assets/du fallback afin que les fichiers manquants renvoient de véritables 404, comme le fait le bloc nginx ci-dessus. -
Bloqueurs de publicité. Les extensions bloquent souvent les fichiers dont le nom contient des mots comme « ad » ou « track ». Vite suggère de renommer les chunks avec
build.rolldownOptions.output.chunkFileNames. Dans Vite 7 et les versions antérieures, l’option s’appellebuild.rollupOptions, que Vite 8 accepte encore comme alias déprécié.build: { rolldownOptions: { output: { chunkFileNames: 'assets/c-[hash].js' } } } -
Coupures réseau. Elles sont intermittentes, touchent n’importe quel nom de fichier et ne renvoient aucun statut HTTP. Le rechargement protégé les couvre également.
Comment identifier la cause en jeu ?
Ouvrez l’onglet Réseau, repérez la requête de chunk en échec et vérifiez deux éléments : son code de statut et son Content-Type. Ensemble, ils permettent d’identifier la cause.
| Ce que montre la requête de chunk en échec | Cause probable | Correctif |
|---|---|---|
| 404, nom de fichier hashé issu d’un ancien build | Décalage de versions | Correctifs 1 à 3 |
200, Content-Type: text/html | Fallback de SPA ou réécriture CDN | Renvoyer de véritables 404 sous /assets/ |
| 404, URL sans le sous-chemin de déploiement | Mauvais base | Définir base |
| Bloquée, nom de fichier contenant des termes liés à la publicité | Extension | Renommer via chunkFileNames |
| Échec sans statut, intermittent | Réseau | Rechargement protégé |
Comme vous ne pouvez généralement pas reproduire l’échec vous-même, ce sont les données de production qui doivent vous indiquer dans quel cas vous vous trouvez. Enregistrez l’identifiant de release avec chaque erreur, dans le cadre de bonnes pratiques de journalisation des erreurs solides. Le suivi des erreurs combiné au session replay permet de vérifier si les échecs se concentrent juste après un déploiement, dans des sessions ouvertes avant celui-ci, ce qui est la signature d’un décalage de versions. Le replay montre également si la garde a rechargé la page une fois et si l’application s’est rétablie. Comme les erreurs « ResizeObserver loop completed », il s’agit d’une erreur de production bruyante qu’il faut classifier, et non masquer.
Corriger la cause racine
L’erreur « Failed to fetch dynamically imported module » est généralement un problème de déploiement qui se manifeste dans le code client. Commencez par le serveur : conservez les assets précédents, servez index.html avec no-cache et assurez-vous que /assets/ ne bascule jamais sur du HTML. Ajoutez ensuite le gestionnaire vite:preloadError protégé et une error boundary en guise de filet de sécurité. Avant de modifier la moindre configuration, ouvrez l’onglet Réseau sur une requête en échec et confirmez la cause à partir de son code de statut et de son type de contenu.
FAQ
S'agit-il du même problème que la ChunkLoadError de webpack ?
Oui, la cause racine est la même, mais l'erreur provient d'un autre endroit. Webpack charge les chunks via son propre runtime, qui rejette avec une ChunkLoadError et un message du type « Loading chunk 42 failed ». Les builds de production de Vite utilisent l'import() natif, si bien que c'est l'erreur du navigateur lui-même qui apparaît. Les correctifs côté serveur sont identiques dans les deux cas : conserver les anciens assets et revalider le HTML. L'événement vite:preloadError n'existe que dans Vite.
Un service worker ou le préchargement des chunks peuvent-ils éviter les erreurs de décalage de versions ?
Ces deux approches figurent parmi les mesures d'atténuation citées dans le guide de dépannage de Vite. Un service worker qui précharge et met en cache l'ensemble des assets garde les chunks de l'ancien build accessibles aux onglets déjà ouverts, même après leur suppression sur le serveur. Le préchargement des chunks dynamiques les récupère avant qu'un déploiement ne puisse les supprimer, mais il n'est d'aucune aide si le navigateur a mis le HTML en cache en raison de ses en-têtes Cache-Control.
Pourquoi cette erreur apparaît-elle sur le serveur de développement de Vite, alors qu'il n'y a aucun déploiement ?
Sur le serveur de développement, la cause habituelle est une extension de navigateur. Le guide de dépannage de Vite indique que des extensions telles que les bloqueurs de publicité peuvent empêcher le client Vite d'envoyer des requêtes au serveur de développement, ce qui produit le même message d'erreur. Pour le confirmer, désactivez les extensions pour localhost ou testez dans un profil de navigateur vierge. Le décalage de versions ne peut pas se produire en développement, car rien ne remplace le build sous un onglet ouvert.
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