Como corrigir o erro "Failed to Fetch Dynamically Imported Module"
Corrija erros Vite Failed to fetch dynamically imported module. Identifique versões incompatíveis, caminhos incorretos, respostas HTML e falhas de rede; mantenha arquivos antigos e controle recargas.
“Failed to fetch dynamically imported module” significa que o navegador não conseguiu carregar um chunk JavaScript solicitado via import(). Em produção, o motivo mais comum é que um novo deploy removeu um chunk que uma aba já aberta ainda espera encontrar.
O padrão é conhecido: você publica uma release, a ferramenta de monitoramento de erros dispara em poucos minutos, mas todas as rotas funcionam quando você mesmo navega por elas. Não há nada quebrado no novo build. As requisições que falham vêm de abas que carregaram o build anterior.
Este artigo aborda o mecanismo que atua no momento do deploy, três correções que se complementam (retenção de assets, um handler de reload e uma proteção contra loops), as causas menos comuns que produzem a mesma mensagem e uma tabela baseada na aba Network para diferenciá-las.
Principais conclusões
- A causa mais comum de “Failed to fetch dynamically imported module” é o version skew (descompasso de versões): uma aba aberta do deploy anterior solicita um chunk carregado sob demanda por um nome de arquivo com hash que não existe mais no servidor.
- Servir o
index.htmlcomCache-Control: no-cachee manter disponíveis os assets do deploy anterior evita a maior parte das falhas por skew antes mesmo de qualquer código no client ser executado. - O evento
vite:preloadErrordo Vite permite recarregar a página quando o carregamento de um chunk falha, mas o handler precisa de uma proteção baseada em timestamp no sessionStorage para não recarregar indefinidamente. - Uma requisição
.jscom falha que retorna 200 comContent-Type: text/htmlindica um problema de fallback no servidor ou na CDN, e não version skew. - Tentar novamente um import dinâmico que falhou não resolve o version skew, porque o arquivo referenciado pelo build antigo não existe mais.
Por que um deploy quebra abas abertas?
O guia de troubleshooting do Vite lista três causas para TypeError: Failed to fetch dynamically imported module: version skew, condições de rede ruins e extensões do navegador bloqueando requisições. O version skew é a que dispara depois de uma release.
Veja a sequência. Um usuário carrega o index.html do build A, que referencia chunks como assets/Settings-a1b2c3.js. Você faz o deploy do build B, e os hashes de conteúdo mudam. A aba do usuário continua executando o build A. Quando ele navega para uma rota com lazy loading, o navegador solicita Settings-a1b2c3.js, recebe um 404, e o import é rejeitado:
TypeError: Failed to fetch dynamically imported module: https://example.com/assets/Settings-a1b2c3.js
Essa é a mensagem no Chromium. Outros navegadores descrevem a mesma falha de forma diferente, então agrupe os erros na sua ferramenta de monitoramento pela causa, e não pelo texto exato.
Raramente é possível reproduzir isso localmente, porque um carregamento novo da página sempre obtém o HTML e os chunks do mesmo build. A falha só acontece em uma aba que carregou o build antigo antes do deploy e solicitou uma rota com lazy loading depois dele. Ela também não tem relação com o erro “Failed to resolve import” do Vite. Aquele é uma falha de resolução em tempo de build. Este acontece em tempo de execução.
Correção 1: manter os assets antigos e revalidar o HTML
A correção mais barata para o version skew acontece no servidor: manter disponíveis os chunks do build anterior e servir o HTML com Cache-Control: no-cache. Se os chunks do build A ainda existirem depois que o build B for publicado, as abas antigas continuam funcionando. As notas sobre tratamento de erros de carregamento do Vite apontam que muitas configurações de hospedagem excluem os assets do deploy anterior e recomendam Cache-Control: no-cache no HTML.
Servir o index.html com Cache-Control: no-cache faz o navegador revalidar o HTML a cada carregamento. Assim, um reload passa a usar os nomes de chunks do novo build em vez dos que foram excluídos. Os assets com hash são o caso oposto. Suas URLs mudam sempre que o conteúdo muda, então eles podem usar com segurança um max-age longo com a diretiva immutable descrita no 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;
}
Faça deploys aditivos: envie o novo assets/ junto com os arquivos antigos e remova os arquivos antigos de forma programada. Por quanto tempo mantê-los é uma decisão caso a caso. O prazo deve ser longo o bastante para cobrir o tempo que seus usuários realisticamente mantêm abas abertas.
Correção 2: recarregar uma vez no vite:preloadError
No client, o Vite dispara um evento vite:preloadError no window quando um import dinâmico falha ao carregar, e recarregar a página a partir desse handler resolve o version skew. A retenção no servidor ajuda, mas em algum momento os chunks antigos são removidos. O erro original fica em event.payload, e chamar event.preventDefault() impede que o Vite o lance. O guia de build sugere recarregar a página a partir desse handler.
Um reload busca o index.html atual, que referencia os chunks do build B. Isso resolve o version skew. Tentar o import novamente não resolve, porque o arquivo para o qual o build A aponta não existe mais no servidor. Só carregar o novo HTML ajuda. (Tentar novamente no mesmo lugar só ajuda em falhas de rede transitórias. A especificação HTML antes armazenava em cache as falhas de fetch de módulos; o whatwg/html#10327 mudou isso, e o suporte varia, como mostra a tabela de compatibilidade do import() no MDN.)
Correção 3: proteger contra loops de reload
Um handler de reload em vite:preloadError precisa de uma proteção contra loops de reload. Se o próprio HTML estiver desatualizado, por exemplo porque um cache de borda ignora o no-cache, ou se o chunk estiver ausente nos dois builds, o reload falha da mesma forma e a página recarrega para sempre. Alguns frameworks já trazem essa recuperação embutida, então consulte primeiro a documentação do seu framework. O Nuxt, por exemplo, recarrega em erros de carregamento de chunk por padrão, e seu helper de reload registra cada reload no sessionStorage e ignora novas solicitações por 10 segundos. Para Vite puro com React, Vue ou Svelte, adicione-a ao seu arquivo 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.
});
O handler recarrega imediatamente, então nada depende do valor com que o import é resolvido após o preventDefault(). Se já houve um reload dentro da janela de tempo, o handler não suprime o erro. O erro se propaga, e um error boundary exibe uma mensagem no 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>
);
}
}
O botão Refresh é acionado pelo usuário, então a proteção não precisa bloqueá-lo. Vue e Svelte têm hooks equivalentes de tratamento de erros. Em qualquer caso, trate a rejeição no nível da rota ou do boundary, porque a documentação do Vite não especifica se todo import dinâmico que falha passa por esse evento.
Causas menos comuns do mesmo erro
“Failed to fetch dynamically imported module” também surge de problemas de caminho, de servidor e de client que não têm nada a ver com deploys. Essas falhas normalmente afetam também as sessões iniciadas depois da release.
-
Caminho
baseincorreto. Se a URL do chunk com falha não tiver um prefixo de caminho sob o qual a aplicação está publicada, a causa é a opçãobasena configuração do Vite, e não um deploy desatualizado. Defina-a de acordo com o caminho de deploy ou passe--baseno momento do build, conforme descrito na documentação de public base path do Vite:// 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 uma URL
.js. Um fallback de SPA ou uma regra de rewrite da CDN responde ao caminho de chunk desconhecido com oindex.html. O navegador então rejeita a resposta como módulo, porque o MIME type não é JavaScript. Exclua/assets/do fallback para que arquivos ausentes retornem 404 de verdade, como faz o bloco nginx acima. -
Bloqueadores de anúncios. Extensões costumam bloquear arquivos cujos nomes contêm palavras como “ad” ou “track”. O Vite sugere renomear os chunks com
build.rolldownOptions.output.chunkFileNames. No Vite 7 e anteriores, a opção ébuild.rollupOptions, que o Vite 8 ainda aceita como alias obsoleto.build: { rolldownOptions: { output: { chunkFileNames: 'assets/c-[hash].js' } } } -
Quedas de rede. São intermitentes, atingem qualquer nome de arquivo e não têm status HTTP. O reload com proteção também cobre esses casos.
Como identificar qual é a sua causa?
Abra a aba Network, encontre a requisição do chunk que falhou e verifique duas coisas: o status code e o Content-Type. Juntos, eles identificam a causa.
| O que a requisição do chunk com falha mostra | Causa provável | Correção |
|---|---|---|
| 404, nome de arquivo com hash de um build anterior | Version skew | Correções 1 a 3 |
200, Content-Type: text/html | Fallback de SPA ou rewrite da CDN | Retornar 404 de verdade em /assets/ |
| 404, URL sem o subcaminho do deploy | base incorreto | Definir base |
| Bloqueada, nome do arquivo contém palavras parecidas com anúncios | Extensão | Renomear via chunkFileNames |
| Falha sem status, intermitente | Rede | Reload com proteção |
Normalmente você não consegue reproduzir a falha por conta própria, então são os dados de produção que precisam indicar em qual caso você está. Registre o identificador da release junto com cada erro, como parte de boas práticas de log de erros. Monitoramento de erros combinado com session replay mostra se as falhas se concentram logo após um deploy em sessões iniciadas antes dele, que é a assinatura do skew. O replay também mostra se a proteção recarregou uma vez e a aplicação se recuperou. Assim como os erros “ResizeObserver loop completed”, este é um erro ruidoso de produção que você deve classificar, e não silenciar.
Corrigindo a causa raiz
“Failed to fetch dynamically imported module” geralmente é um problema de deploy que se manifesta no código do client. Comece pelo servidor: mantenha os assets anteriores, sirva o index.html com no-cache e garanta que /assets/ nunca caia no fallback para HTML. Depois, adicione o handler de vite:preloadError com proteção e um error boundary como rede de segurança. Antes de alterar qualquer configuração, abra a aba Network em uma requisição com falha e confirme a causa pelo status code e pelo content type.
Perguntas frequentes
É o mesmo problema do ChunkLoadError do webpack?
Sim, a causa raiz é a mesma, mas o erro vem de outro lugar. O webpack carrega chunks pelo seu próprio runtime, que rejeita com ChunkLoadError e uma mensagem como 'Loading chunk 42 failed'. Os builds de produção do Vite usam o import() nativo, então aparece o erro do próprio navegador. As correções no servidor são as mesmas para ambos: reter os assets antigos e revalidar o HTML. O evento vite:preloadError existe apenas no Vite.
Um service worker ou o prefetch de chunks pode evitar erros de version skew?
Ambos são mitigações listadas no guia de troubleshooting do Vite. Um service worker que faz prefetch e cache de todos os assets mantém os chunks do build antigo disponíveis para as abas já abertas, mesmo depois que o servidor os exclui. Fazer prefetch dos chunks dinâmicos os carrega antes que um deploy possa removê-los, mas isso não ajuda se o navegador tiver armazenado o HTML em cache por causa dos headers Cache-Control.
Por que esse erro aparece no servidor de desenvolvimento do Vite, onde não há deploy?
No servidor de desenvolvimento, a causa mais comum é uma extensão do navegador. O guia de troubleshooting do Vite observa que extensões como bloqueadores de anúncios podem impedir que o client do Vite envie requisições ao servidor de desenvolvimento, o que produz a mesma mensagem de erro. Para confirmar, desative as extensões para localhost ou teste em um perfil limpo do navegador. O version skew não pode acontecer em desenvolvimento, porque nada substitui o build por baixo de uma aba aberta.
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