remix-run/react-router · warning

Detected a manifest version mismatch during eager route disc

Error message

Detected a manifest version mismatch during eager route discovery. The next navigation/fetch to an undiscovered route will result in a new document navigation to sync up with the latest manifest.

What it means

The fog-of-war version-mismatch machinery in two modes: here it fires during eager route discovery (links/forms present at initial load) when a fetched manifest patch has a different version than the page's baked-in manifest, and errorReloadPath is null. Rather than hard-reloading while the user sits on the page, it warns and returns true so the NEXT navigation/fetch to an undiscovered route degrades to a full document load that syncs manifests — avoiding both a disruptive immediate reload and the `React.useContext` crash that would otherwise occur.

Source

Thrown at packages/react-router/lib/dom/ssr/fog-of-war.ts:259

): Promise<boolean> {
  if (!needsReload) {
    // Reset loop-detection on a successful response
    try {
      sessionStorage.removeItem(MANIFEST_VERSION_STORAGE_KEY);
    } catch {
      // Session storage unavailable
    }
    return false;
  }

  if (!errorReloadPath) {
    // No-op during eager route discovery so we will trigger a hard reload
    // of the destination during the next navigation instead of reloading
    // while the user is sitting on the current page. Slightly more
    // disruptive on fetcher calls because we reload the current page, but
    // it's better than the `React.useContext` error that occurs without
    // this detection.
    console.warn(
      "Detected a manifest version mismatch during eager route discovery. " +
        "The next navigation/fetch to an undiscovered route will result in " +
        "a new document navigation to sync up with the latest manifest.",
    );
    return true;
  }

  try {
    // This will hard reload the destination path on navigations, or the
    // current path on fetcher calls
    if (sessionStorage.getItem(MANIFEST_VERSION_STORAGE_KEY) === version) {
      // We've already tried fixing for this version, don't try again to
      // avoid loops - just let this navigation/fetch 404
      console.error(
        "Unable to discover routes due to manifest version mismatch.",
      );
      return true;
    }

View on GitHub (pinned to 7aea711dd1)

Solutions

1. No app fix required — the next navigation performs one full document load and resyncs; this is the designed recovery path
2. Send `Cache-Control: no-store` for /__manifest and index HTML so patch fetches always reflect the live build
3. Deploy atomically (single cutover to the new build) so the document and manifest versions never straddle two builds
4. If every navigation does a full load, all builds in rotation must be reconciled: purge CDN caches and confirm every instance serves one version

// framework-internal: warns once and defers a document navigation;
// if you add a version ping, follow the same one-shot guard:
let key = "app-version";
if (latestVersion !== embeddedVersion && sessionStorage.getItem(key) !== latestVersion) {
  sessionStorage.setItem(key, latestVersion);
  location.reload();
}

When it happens

Trigger: Eager discovery fetches /__manifest patches after the server deployed a new build (or a proxy/CDN serves a mismatched version) while errorReloadPath is unavailable — the mismatch is deferred to the next navigation.

Common situations: Deploys happening while users hold tabs open; stale-cached manifest or HTML at the edge; rolling deploys serving mixed versions; test environments rebuilt frequently while browser tabs persist.

Related errors

• Detected manifest version mismatch, reloading...
• ${res.status} ${res.statusText}
• Custom Vite manifest paths are not supported
• The `routeDiscovery.manifestPath` config must be a root-rela
• Unable to fetch new route matches from the server

AI-assisted analysis of remix-run/react-router@7aea711dd1 (2026-08-18). Data as JSON: /api/errors/ef6fea342c919043. Report an issue: GitHub.