12k
All articles

„Failed to Fetch Dynamically Imported Module“ beheben

Beheben Sie Vite-Fehler Failed to fetch dynamically imported module. Erkennen Sie Versionskonflikte, falsche Pfade, HTML-Antworten und Netzwerkausfälle; behalten Sie alte Dateien und begrenzen Sie Neuladevorgänge.

OpenReplay Team
OpenReplay Team
„Failed to Fetch Dynamically Imported Module“ beheben

„Failed to fetch dynamically imported module“ bedeutet, dass der Browser einen JavaScript-Chunk nicht laden konnte, der über import() angefordert wurde. In Produktion liegt das meist daran, dass ein neues Deployment einen Chunk entfernt hat, den ein bereits geöffneter Tab noch erwartet.

Das Muster ist bekannt: Sie veröffentlichen ein Release, innerhalb weniger Minuten schlägt das Error-Tracking an, und trotzdem funktioniert jede Route, wenn Sie sich selbst durchklicken. Am neuen Build ist nichts kaputt. Die fehlschlagenden Requests stammen aus Tabs, die den vorherigen Build geladen haben.

Dieser Artikel erklärt den Mechanismus beim Deployment, drei aufeinander aufbauende Lösungen (Aufbewahrung alter Assets, ein Reload-Handler und ein Schutz vor Reload-Schleifen), die selteneren Ursachen, die dieselbe Meldung erzeugen, sowie eine Tabelle für den Network-Tab, mit der Sie die Ursachen auseinanderhalten.

Die wichtigsten Punkte

  • Die häufigste Ursache für „Failed to fetch dynamically imported module“ ist Version Skew: Ein offener Tab aus dem vorherigen Deployment fordert einen Lazy-Chunk über einen gehashten Dateinamen an, der auf dem Server nicht mehr existiert.
  • Wenn Sie index.html mit Cache-Control: no-cache ausliefern und die Assets des vorherigen Deployments verfügbar halten, verhindern Sie die meisten Skew-Fehler, bevor überhaupt clientseitiger Code ausgeführt wird.
  • Mit dem Vite-Event vite:preloadError können Sie die Seite bei einem fehlgeschlagenen Chunk-Load neu laden. Der Handler braucht jedoch einen Zeitstempel-Guard in sessionStorage, damit er nicht endlos neu lädt.
  • Ein fehlschlagender .js-Request, der 200 mit Content-Type: text/html zurückgibt, ist ein Fallback-Problem auf Server- oder CDN-Seite, kein Version Skew.
  • Ein erneuter Versuch des fehlgeschlagenen dynamischen Imports kann Version Skew nicht beheben, weil die Datei, auf die der alte Build verweist, nicht mehr existiert.

Warum bricht ein Deployment offene Tabs?

Der Vite Troubleshooting Guide nennt drei Ursachen für TypeError: Failed to fetch dynamically imported module: Version Skew, schlechte Netzwerkbedingungen und Browser-Erweiterungen, die Requests blockieren. Version Skew ist diejenige, die nach einem Release sprunghaft ansteigt.

Der Ablauf sieht so aus: Ein Nutzer lädt index.html aus Build A, das auf Chunks wie assets/Settings-a1b2c3.js verweist. Sie deployen Build B, und die Content-Hashes ändern sich. Im Tab des Nutzers läuft weiterhin Build A. Navigiert er zu einer Lazy-Route, fordert der Browser Settings-a1b2c3.js an, erhält einen 404, und der Import wird mit einem Fehler abgewiesen:

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

Das ist die Formulierung von Chromium. Andere Browser beschreiben denselben Fehler anders, gruppieren Sie in Ihrem Tracker also nach Ursache, nicht nach exaktem Wortlaut.

Lokal lässt sich das selten reproduzieren, denn ein frischer Seitenaufruf erhält HTML und Chunks immer aus demselben Build. Der Fehler tritt nur in einem Tab auf, der den alten Build vor dem Deployment geladen und danach eine Lazy-Route angefordert hat. Er hat auch nichts mit Vites Fehler „Failed to resolve import“ zu tun. Dabei handelt es sich um einen Auflösungsfehler zur Build-Zeit, während dieser hier zur Laufzeit auftritt.

Lösung 1: Alte Assets behalten und das HTML revalidieren

Die günstigste Lösung für Version Skew liegt auf dem Server: Halten Sie die Chunks des vorherigen Builds verfügbar und liefern Sie das HTML mit Cache-Control: no-cache aus. Wenn die Chunks von Build A nach dem Release von Build B noch existieren, funktionieren alte Tabs weiter. Die Hinweise zur Behandlung von Ladefehlern in der Vite-Dokumentation weisen darauf hin, dass viele Hosting-Setups die Assets des vorherigen Deployments löschen, und empfehlen Cache-Control: no-cache für das HTML.

Wird index.html mit Cache-Control: no-cache ausgeliefert, revalidiert der Browser das HTML bei jedem Laden. Ein Reload übernimmt dann die Chunk-Namen des neuen Builds statt der gelöschten. Bei gehashten Assets ist es umgekehrt: Ihre URLs ändern sich, sobald sich ihr Inhalt ändert, daher können sie bedenkenlos ein langes max-age mit der auf MDN beschriebenen immutable-Direktive verwenden.

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

Gestalten Sie Ihre Deployments additiv: Laden Sie die neuen assets/ neben die alten hoch und bereinigen Sie alte Dateien zeitgesteuert. Wie lange Sie sie aufbewahren, ist eine Ermessensfrage. Der Zeitraum sollte lang genug sein, um die offenen Tabs zu überdauern, die Ihre Nutzer realistischerweise behalten.

Lösung 2: Einmalig bei vite:preloadError neu laden

Auf dem Client löst Vite ein vite:preloadError-Event auf window aus, wenn ein dynamischer Import nicht geladen werden kann. Ein Reload der Seite aus diesem Handler heraus behebt Version Skew. Die serverseitige Aufbewahrung hilft, aber irgendwann werden alte Chunks bereinigt. Der ursprüngliche Fehler steht in event.payload, und ein Aufruf von event.preventDefault() verhindert, dass Vite ihn wirft. Der Build Guide empfiehlt, die Seite aus diesem Handler heraus neu zu laden.

Ein Reload ruft das aktuelle index.html ab, das auf die Chunks von Build B verweist. Damit ist Version Skew behoben. Ein erneuter Versuch des Imports hilft dagegen nicht, weil die Datei, auf die Build A verweist, auf dem Server nicht mehr existiert. Nur das Laden des neuen HTML hilft. (Ein erneuter Versuch an Ort und Stelle hilft nur bei vorübergehenden Netzwerkfehlern. Die HTML-Spezifikation hat fehlgeschlagene Modul-Fetches früher gecacht; whatwg/html#10327 hat das geändert, und die Unterstützung variiert, wie die Kompatibilitätstabelle für import() auf MDN zeigt.)

Lösung 3: Vor Reload-Schleifen schützen

Ein Reload-Handler für vite:preloadError braucht einen Schutz vor Reload-Schleifen. Ist das HTML selbst veraltet, etwa weil ein Edge-Cache no-cache ignoriert, oder fehlt der Chunk in beiden Builds, schlägt der Reload auf dieselbe Weise fehl, und die Seite lädt endlos neu. Manche Frameworks bringen diese Wiederherstellung bereits mit, prüfen Sie also zuerst die Dokumentation Ihres Frameworks. Nuxt zum Beispiel lädt bei Chunk-Ladefehlern standardmäßig neu; sein Reload-Helper speichert jeden Reload in sessionStorage und ignoriert wiederholte Anfragen für 10 Sekunden. Bei reinem Vite mit React, Vue oder Svelte fügen Sie den Schutz in Ihre Entry-Datei ein:

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

Der Handler lädt sofort neu, daher hängt nichts davon ab, womit der Import nach preventDefault() aufgelöst wird. Hat innerhalb des Zeitfensters bereits ein Reload stattgefunden, unterdrückt der Handler den Fehler nicht. Der Fehler wird weitergereicht, und eine Error Boundary zeigt stattdessen eine Meldung an:

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

Der Refresh-Button wird vom Nutzer ausgelöst, daher muss der Guard ihn nicht blockieren. Vue und Svelte bieten vergleichbare Hooks zur Fehlerbehandlung. Behandeln Sie die Rejection in jedem Fall auf Routen- oder Boundary-Ebene, denn die Vite-Dokumentation legt nicht fest, ob jeder fehlgeschlagene dynamische Import dieses Event durchläuft.

Seltenere Ursachen für denselben Fehler

„Failed to fetch dynamically imported module“ entsteht auch durch Pfad-, Server- und Client-Probleme, die nichts mit Deployments zu tun haben. Diese Fehler betreffen in der Regel auch Sessions, die erst nach dem Release begonnen haben.

  • Falscher base-Pfad. Fehlt in der URL des fehlschlagenden Chunks ein Pfadpräfix, unter dem die App deployt ist, liegt die Ursache in der Option base der Vite-Konfiguration, nicht in einem veralteten Deployment. Setzen Sie sie passend zum Deployment-Pfad oder übergeben Sie --base zur Build-Zeit, wie in der Vite-Dokumentation zum Public Base Path beschrieben:

    // 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 für eine .js-URL ausgeliefert. Ein SPA-Fallback oder ein CDN-Rewrite beantwortet den unbekannten Chunk-Pfad mit index.html. Der Browser weist die Antwort dann als Modul zurück, weil ihr MIME-Typ kein JavaScript ist. Nehmen Sie /assets/ vom Fallback aus, damit fehlende Dateien echte 404-Antworten liefern, so wie im nginx-Block oben.

  • Werbeblocker. Erweiterungen blockieren häufig Dateien, deren Namen Wörter wie „ad“ oder „track“ enthalten. Vite empfiehlt, Chunks über build.rolldownOptions.output.chunkFileNames umzubenennen. In Vite 7 und älter heißt die Option build.rollupOptions; Vite 8 akzeptiert sie weiterhin als veralteten Alias.

    build: { rolldownOptions: { output: { chunkFileNames: 'assets/c-[hash].js' } } }
  • Netzwerkabbrüche. Sie treten sporadisch auf, betreffen beliebige Dateinamen und haben keinen HTTP-Statuscode. Der abgesicherte Reload deckt auch sie ab.

Wie erkennen Sie, welche Ursache vorliegt?

Öffnen Sie den Network-Tab, suchen Sie den fehlschlagenden Chunk-Request und prüfen Sie zwei Dinge: seinen Statuscode und seinen Content-Type. Zusammen identifizieren sie die Ursache.

Was der fehlschlagende Chunk-Request zeigtWahrscheinliche UrsacheLösung
404, gehashter Dateiname aus einem älteren BuildVersion SkewLösungen 1 bis 3
200, Content-Type: text/htmlSPA-Fallback oder CDN-RewriteUnter /assets/ echte 404-Antworten liefern
404, URL ohne den Deployment-UnterpfadFalsches basebase setzen
Blockiert, Dateiname enthält werbeähnliche WörterErweiterungUmbenennen über chunkFileNames
Fehlgeschlagen ohne Status, sporadischNetzwerkAbgesicherter Reload

Da Sie den Fehler meist nicht selbst reproduzieren können, müssen Produktionsdaten Ihnen verraten, welcher Fall vorliegt. Erfassen Sie bei jedem Fehler die Release-Kennung, als Teil solider Praktiken für das Error-Logging. Error-Tracking in Kombination mit Session Replay zeigt, ob sich die Fehler kurz nach einem Deployment in Sessions häufen, die vor dem Deployment begonnen haben – das typische Muster von Skew. Das Replay zeigt außerdem, ob der Guard einmal neu geladen und die Seite sich davon erholt hat. Wie Fehler vom Typ „ResizeObserver loop completed“ ist dies ein lauter Produktionsfehler, den Sie klassifizieren statt stummschalten sollten.

Die eigentliche Ursache beheben

„Failed to fetch dynamically imported module“ ist meist ein Deployment-Problem, das sich im Client-Code bemerkbar macht. Beginnen Sie auf dem Server: Behalten Sie vorherige Assets, liefern Sie index.html mit no-cache aus und stellen Sie sicher, dass /assets/ niemals auf HTML zurückfällt. Ergänzen Sie dann den abgesicherten vite:preloadError-Handler und eine Error Boundary als Sicherheitsnetz. Bevor Sie eine Konfiguration ändern, öffnen Sie den Network-Tab bei einem fehlschlagenden Request und bestätigen Sie die Ursache anhand von Statuscode und Content-Type.

FAQs

Ist das dasselbe Problem wie der ChunkLoadError von webpack?

Ja, die eigentliche Ursache ist dieselbe, aber der Fehler entsteht an einer anderen Stelle. Webpack lädt Chunks über seine eigene Runtime, die mit ChunkLoadError und einer Meldung wie 'Loading chunk 42 failed' abbricht. Vite-Produktions-Builds verwenden natives import(), daher erscheint der Fehler des Browsers selbst. Die serverseitigen Lösungen sind für beide gleich: alte Assets behalten und das HTML revalidieren. Das Event vite:preloadError gibt es nur in Vite.

Können ein Service Worker oder das Prefetching von Chunks Version-Skew-Fehler verhindern?

Beides wird im Vite Troubleshooting Guide als Gegenmaßnahme aufgeführt. Ein Service Worker, der alle Assets vorab lädt und cacht, hält die Chunks des alten Builds für bereits geöffnete Tabs verfügbar, selbst nachdem der Server sie gelöscht hat. Das Prefetching dynamischer Chunks lädt diese, bevor ein Deployment sie entfernen kann, hilft aber nicht, wenn der Browser das HTML aufgrund seiner Cache-Control-Header gecacht hat.

Warum tritt dieser Fehler auf dem Vite-Dev-Server auf, obwohl es dort kein Deployment gibt?

Auf dem Dev-Server ist die übliche Ursache eine Browser-Erweiterung. Der Vite Troubleshooting Guide weist darauf hin, dass Erweiterungen wie Werbeblocker den Vite-Client daran hindern können, Requests an den Dev-Server zu senden, was dieselbe Fehlermeldung erzeugt. Zur Überprüfung deaktivieren Sie Erweiterungen für localhost oder testen in einem sauberen Browserprofil. Version Skew kann in der Entwicklung nicht auftreten, weil nichts den Build unter einem geöffneten Tab ersetzt.

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.