12k
All articles

Cómo solucionar el error "Failed to Fetch Dynamically Imported Module"

Corrige errores Vite Failed to fetch dynamically imported module. Detecta versiones desincronizadas, rutas erróneas, respuestas HTML y fallos de red; conserva archivos y recarga con control.

OpenReplay Team
OpenReplay Team
Cómo solucionar el error "Failed to Fetch Dynamically Imported Module"

“Failed to fetch dynamically imported module” significa que el navegador no pudo cargar un chunk de JavaScript solicitado mediante import(). En producción, la causa habitual es que un nuevo despliegue eliminó un chunk que una pestaña ya abierta todavía espera encontrar.

El patrón es conocido: publicas una versión, la herramienta de seguimiento de errores se dispara a los pocos minutos y, sin embargo, todas las rutas funcionan cuando las recorres tú mismo. No hay nada roto en la nueva build. Las peticiones que fallan provienen de pestañas que cargaron la build anterior.

Este artículo explica el mecanismo que se produce durante el despliegue, tres soluciones que se complementan entre sí (conservación de assets, un manejador de recarga y una protección contra bucles), las causas menos comunes que generan el mismo mensaje y una tabla basada en la pestaña de red que permite distinguirlas.

Puntos clave

  • La causa más común de “Failed to fetch dynamically imported module” es el desfase de versiones (version skew): una pestaña abierta del despliegue anterior solicita un chunk de carga diferida mediante un nombre de archivo con hash que ya no existe en el servidor.
  • Servir index.html con Cache-Control: no-cache y mantener disponibles los assets del despliegue anterior evita la mayoría de los fallos por desfase antes de que se ejecute código alguno en el cliente.
  • El evento vite:preloadError de Vite permite recargar la página cuando falla la carga de un chunk, pero el manejador necesita una protección basada en una marca de tiempo en sessionStorage para no recargar indefinidamente.
  • Una petición .js fallida que devuelve 200 con Content-Type: text/html es un problema de fallback del servidor o de la CDN, no un desfase de versiones.
  • Reintentar una importación dinámica fallida no puede resolver el desfase de versiones, porque el archivo al que hace referencia la build anterior ya no existe.

¿Por qué un despliegue rompe las pestañas abiertas?

La guía de resolución de problemas de Vite enumera tres causas para TypeError: Failed to fetch dynamically imported module: el desfase de versiones, las malas condiciones de red y las extensiones del navegador que bloquean peticiones. El desfase de versiones es la que se dispara tras una nueva versión.

Esta es la secuencia. Un usuario carga index.html de la build A, que hace referencia a chunks como assets/Settings-a1b2c3.js. Despliegas la build B y los hashes de contenido cambian. La pestaña del usuario sigue ejecutando la build A. Cuando navega a una ruta con carga diferida, el navegador solicita Settings-a1b2c3.js, recibe un 404 y la importación se rechaza:

TypeError: Failed to fetch dynamically imported module: https://example.com/assets/Settings-a1b2c3.js

Esa es la redacción de Chromium. Otros navegadores expresan el mismo fallo de forma distinta, así que agrupa los errores por causa en tu herramienta de seguimiento, no por la cadena exacta.

Rara vez podrás reproducirlo en local, porque una carga de página nueva siempre obtiene el HTML y los chunks de la misma build. El fallo solo ocurre en una pestaña que cargó la build anterior antes del despliegue y solicitó una ruta con carga diferida después. Tampoco tiene relación con el error “Failed to resolve import” de Vite. Aquel es un fallo de resolución en tiempo de build. Este ocurre en tiempo de ejecución.

Solución 1: conservar los assets antiguos y revalidar el HTML

La solución más económica para el desfase de versiones se aplica en el servidor: mantener disponibles los chunks de la build anterior y servir el HTML con Cache-Control: no-cache. Si los chunks de la build A siguen existiendo después de publicar la build B, las pestañas antiguas siguen funcionando. Las notas sobre gestión de errores de carga de Vite señalan que muchas configuraciones de hosting eliminan los assets del despliegue anterior y recomiendan Cache-Control: no-cache para el HTML.

Servir index.html con Cache-Control: no-cache hace que el navegador revalide el HTML en cada carga. Así, una recarga obtiene los nombres de los chunks de la nueva build en lugar de los eliminados. Los assets con hash son el caso opuesto. Sus URL cambian cada vez que cambia su contenido, por lo que pueden usar sin riesgo un max-age largo con la directiva immutable descrita en 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;
}

Haz que tus despliegues sean aditivos: sube el nuevo assets/ junto a los archivos antiguos y luego elimina los archivos viejos de forma programada. Cuánto tiempo conservarlos es una cuestión de criterio. Debe ser suficiente para cubrir el tiempo que tus usuarios mantienen realmente abiertas sus pestañas.

Solución 2: recargar una vez con vite:preloadError

En el cliente, Vite emite un evento vite:preloadError sobre window cuando falla la carga de una importación dinámica, y recargar la página desde ese manejador permite recuperarse del desfase de versiones. La conservación en el servidor ayuda, pero tarde o temprano los chunks antiguos se eliminan. El error original está en event.payload, y llamar a event.preventDefault() impide que Vite lo lance. La guía de build sugiere recargar la página desde este manejador.

Una recarga obtiene el index.html actual, que hace referencia a los chunks de la build B. Eso resuelve el desfase de versiones. Reintentar la importación no lo hace, porque el archivo al que apunta la build A ya no existe en el servidor. Solo cargar el nuevo HTML sirve de algo. (Reintentar sin recargar solo ayuda ante fallos de red transitorios. La especificación HTML almacenaba en caché las cargas de módulos fallidas; whatwg/html#10327 cambió ese comportamiento, y el soporte varía, como muestra la tabla de compatibilidad de import() en MDN).

Solución 3: protegerse contra los bucles de recarga

Un manejador de recarga basado en vite:preloadError necesita una protección contra los bucles de recarga. Si el propio HTML está obsoleto, por ejemplo porque una caché de borde ignora no-cache, o si el chunk falta en ambas builds, la recarga falla de la misma manera y la página se recarga indefinidamente. Algunos frameworks incluyen esta recuperación de serie, así que consulta primero la documentación del tuyo. Nuxt, por ejemplo, recarga por defecto ante errores de carga de chunks, y su helper de recarga registra cada recarga en sessionStorage e ignora las solicitudes repetidas durante 10 segundos. Con Vite puro y React, Vue o Svelte, añádela a tu archivo de entrada:

// 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.
});

El manejador recarga de inmediato, por lo que nada depende de cómo se resuelva la importación tras preventDefault(). Si ya se produjo una recarga dentro de la ventana de tiempo, el manejador no suprime el error. El error se propaga y un error boundary muestra un mensaje en su lugar:

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>
    );
  }
}

El botón Refresh lo activa el propio usuario, así que la protección no necesita bloquearlo. Vue y Svelte disponen de hooks de gestión de errores equivalentes. En cualquier caso, gestiona el rechazo a nivel de ruta o de boundary, porque la documentación de Vite no especifica si todas las importaciones dinámicas fallidas pasan por este evento.

Causas menos comunes del mismo error

“Failed to fetch dynamically imported module” también puede deberse a problemas de rutas, del servidor o del cliente que no tienen nada que ver con los despliegues. Estos fallos suelen afectar también a sesiones iniciadas después de la publicación.

  • Ruta base incorrecta. Si a la URL del chunk que falla le falta un prefijo de ruta bajo el que está desplegada la aplicación, la causa es la opción base de la configuración de Vite, no un despliegue obsoleto. Ajústala para que coincida con la ruta de despliegue, o pasa --base al hacer la build, como se explica en la documentación de Vite sobre la ruta base pública:

    // 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 servido para una URL .js. Un fallback de SPA o una reescritura de la CDN responde a la ruta desconocida del chunk con index.html. El navegador rechaza entonces la respuesta como módulo porque su tipo MIME no es JavaScript. Excluye /assets/ del fallback para que los archivos inexistentes devuelvan 404 reales, como hace el bloque de nginx anterior.

  • Bloqueadores de anuncios. Las extensiones suelen bloquear archivos cuyo nombre contiene palabras como “ad” o “track”. Vite sugiere renombrar los chunks con build.rolldownOptions.output.chunkFileNames. En Vite 7 y versiones anteriores la opción es build.rollupOptions, que Vite 8 todavía acepta como alias obsoleto.

    build: { rolldownOptions: { output: { chunkFileNames: 'assets/c-[hash].js' } } }
  • Caídas de red. Son intermitentes, afectan a cualquier nombre de archivo y no tienen código de estado HTTP. La recarga con protección también las cubre.

¿Cómo saber cuál es la causa?

Abre la pestaña de red, localiza la petición del chunk que falla y comprueba dos cosas: su código de estado y su Content-Type. Juntos identifican la causa.

Qué muestra la petición del chunk fallidoCausa probableSolución
404, nombre de archivo con hash de una build anteriorDesfase de versionesSoluciones 1 a 3
200, Content-Type: text/htmlFallback de SPA o reescritura de la CDNDevolver 404 reales en /assets/
404, a la URL le falta la subruta de desplieguebase incorrectoConfigurar base
Bloqueada, el nombre contiene palabras similares a “ad”ExtensiónRenombrar mediante chunkFileNames
Fallida sin código de estado, intermitenteRedRecarga con protección

Normalmente no podrás reproducir el fallo por tu cuenta, así que deben ser los datos de producción los que te indiquen en qué caso estás. Registra el identificador de la versión con cada error, como parte de unas buenas prácticas de registro de errores. El seguimiento de errores combinado con la reproducción de sesiones muestra si los fallos se concentran justo después de un despliegue en sesiones que comenzaron antes de él, que es la señal característica del desfase. La reproducción también muestra si la protección recargó una vez y se recuperó. Al igual que los errores “ResizeObserver loop completed”, se trata de un error ruidoso de producción que conviene clasificar, no silenciar.

Solucionar la causa raíz

“Failed to fetch dynamically imported module” suele ser un problema de despliegue que se manifiesta en el código del cliente. Empieza por el servidor: conserva los assets anteriores, sirve index.html con no-cache y asegúrate de que /assets/ nunca recurra al HTML como fallback. Después, añade el manejador de vite:preloadError con protección y un error boundary como red de seguridad. Antes de modificar cualquier configuración, abre la pestaña de red en una petición fallida y confirma la causa a partir de su código de estado y su tipo de contenido.

Preguntas frecuentes

¿Es el mismo problema que el ChunkLoadError de webpack?

Sí, la causa raíz es la misma, pero el error se origina en otro lugar. Webpack carga los chunks a través de su propio runtime, que rechaza con ChunkLoadError y un mensaje como 'Loading chunk 42 failed'. Las builds de producción de Vite usan import() nativo, por lo que aparece el error propio del navegador. Las soluciones del lado del servidor son las mismas para ambos: conservar los assets antiguos y revalidar el HTML. El evento vite:preloadError solo existe en Vite.

¿Puede un service worker o la precarga de chunks evitar los errores por desfase de versiones?

Ambas son medidas de mitigación que recoge la guía de resolución de problemas de Vite. Un service worker que precarga y almacena en caché todos los assets mantiene los chunks de la build anterior disponibles para las pestañas ya abiertas, incluso después de que el servidor los elimine. Precargar los chunks dinámicos los descarga antes de que un despliegue pueda eliminarlos, pero no sirve de nada si el navegador ha almacenado en caché el HTML debido a sus cabeceras Cache-Control.

¿Por qué aparece este error en el servidor de desarrollo de Vite, donde no hay despliegues?

En el servidor de desarrollo, la causa habitual es una extensión del navegador. La guía de resolución de problemas de Vite señala que extensiones como los bloqueadores de anuncios pueden impedir que el cliente de Vite envíe peticiones al servidor de desarrollo, lo que produce el mismo mensaje de error. Para confirmarlo, desactiva las extensiones para localhost o prueba en un perfil de navegador limpio. El desfase de versiones no puede darse en desarrollo, porque nada reemplaza la build bajo una pestaña abierta.

DevTools for the frontend

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

We use cookies to improve your experience. By using our site, you accept cookies.