sodcalculator

10 Tech How-To

Verify a Stale JS Chunk Behind an App Error

Guide 10-53412 · Updated · Step by step

When a web app fails after a new deployment, the culprit is often a stale JavaScript chunk: the browser loaded an old version of a file that no longer matches the server’s current code. This guide shows you how to confirm that a stale chunk is causing the error, using browser DevTools and a few simple checks. You’ll need access to the app’s console, network tab, and preferably the deployment history.

What You’ll Need

  • A browser with developer tools (Chrome, Firefox, Edge, or Safari).
  • The URL of the page that shows the error.
  • Access to the server’s deployment logs or a way to see when the last deploy happened (optional but helpful).
  • If the app uses a build tool (Webpack, Vite, etc.), know where the built files are served from (e.g., /static/js/).

Step-by-Step

  1. Reproduce the error in a fresh tab. Open the affected page in a new tab or incognito window. If the error disappears, it’s likely a caching issue. If it persists, note the exact error message.
  2. Open the browser’s Developer Tools (F12 or Ctrl+Shift+I / Cmd+Option+I). Go to the Console tab. Look for errors that mention chunk, loading, module, or a 404 status. Typical messages include: ChunkLoadError: Loading chunk 12 failed. or Failed to fetch dynamically imported module.
  3. Check the Network tab. Refresh the page while the Network tab is open. Look for requests ending in .js that return a 404 or 304 Not Modified. A 404 means the file no longer exists on the server – a strong sign of a stale chunk. A 304 might indicate the browser is using a cached version.
  4. Compare the requested filename with the server’s current file list. In the Network tab, click on the failing JS request and note its full URL (e.g., /static/js/main.abc123.js). Now, open the same URL directly in a new tab (or use the server’s directory listing if enabled). If you get a 404, the file is gone. If you see a different filename (like main.def456.js), the old one is stale.
  5. Check the HTML response. View the page source (Ctrl+U) and look for the <script> tags. Note the filenames listed there. Compare them with the filenames in the Network tab. If the HTML references a different chunk than the one that failed, the browser is using an old cached HTML that points to old chunks.
  6. Force a hard reload. Press Ctrl+Shift+R (or Cmd+Shift+R on Mac) to bypass the browser cache. If the error disappears, it’s confirmed that a stale chunk was being served. If not, proceed to the next step.
  7. Disable cache in DevTools and reload. In the Network tab, check the Disable cache checkbox (while DevTools is open), then reload. This simulates a fresh visitor. If the error goes away, the issue is definitely cache-related.
  8. Check the server’s deployment timestamp. If you have access, look at when the last deployment occurred. If the error started right after a deploy, and the chunk that fails is from a build that predates that deploy, it’s a stale chunk.
  9. Look at the chunk’s content hash. Most modern build tools append a content hash to filenames (e.g., vendor.8f3k2.js). If the hash in the Network tab doesn’t match the hash in the current build output (you can check the build folder on the server), it’s stale.
  10. Test with a query string. Append a dummy query string to the failing chunk URL (e.g., /static/js/main.abc123.js?v=2) and load it directly. If it returns the new content, the server has the new file, but the browser is caching the old one.

Common Mistakes

  • Confusing a network error with a stale chunk. A 500 error from the server is not a stale chunk issue. Only 404s on JS files point to stale chunks.
  • Assuming a hard reload is enough. Hard reload bypasses the browser cache, but if a service worker is active, it might still serve old files. Check the Application tab > Service Workers and unregister any active workers.
  • Ignoring the HTML document cache. The HTML file itself is often cached. If it’s old, it will reference old chunks. Check the response headers for Cache-Control on the HTML document.
  • Not checking all tabs/windows. A stale chunk might be loaded by a background tab or a service worker. Close all tabs of the app and reopen.
  • Overlooking CDN caching. If the app uses a CDN, the CDN might have cached the old JS file. Purge the CDN cache for the affected paths.

Tips

  • Use the Coverage tab in DevTools to see which JS files are actually being used. If a file is 100% unused but still loaded, it might be stale.
  • Set up a build version check in your app. For example, after loading, fetch a version.json and compare it with the current build. If they differ, prompt the user to refresh.
  • Configure your server to send Cache-Control: no-cache for the HTML document, but use long-term caching for hashed JS files. This ensures the HTML always points to the latest chunks.
  • If you use Webpack, enable output.chunkLoadingGlobal to a unique name to avoid conflicts with old chunks.
  • In development, use webpack-dev-server with hot: true to avoid stale chunks during development.

Troubleshooting

The error still appears after a hard reload. This means the server itself is serving an old chunk. Check the server’s file system – the old file might still be there, or the deployment didn’t remove old files. Clear the server’s cache or redeploy.

No 404 appears in the Network tab, but the error persists. The chunk might be loading successfully but contain code that throws an error because it’s incompatible with the new HTML or other chunks. Check the console for a different error message, like a syntax error or a missing export.

The error is intermittent. This could be a race condition where some chunks load from cache and others from the network. Try clearing the cache and doing a full reload. If it persists, check if a service worker is intercepting requests.

You can’t reproduce the error at all. It might be a one-time issue due to a partial deployment. Ask the user to clear their cache or try a different browser. If it doesn’t recur, it’s likely a stale chunk that has since been resolved.

The app uses a service worker. Service workers can aggressively cache files. In the Application tab, unregister the service worker and clear the storage. Then reload.

Frequently Asked Questions

Q: How do I know if a chunk is stale without seeing a 404?
A: Compare the file’s content hash with the hash in the latest build. If they differ, it’s stale. Also, check the HTML document’s script tags – if they reference a different filename than what’s loaded, that’s a sign.

Q: Will a hard reload always fix a stale chunk?
A: No. A hard reload bypasses the browser’s HTTP cache, but if a service worker is controlling the page, it can still serve old files. You need to unregister the service worker as well.

Q: Why does this happen only to some users?
A: Users who visited the site before the deploy have cached old chunks. New visitors get the new chunks. It’s a classic caching problem.

Q: Can a stale chunk cause a blank page?
A: Yes. If the main entry point loads a stale chunk that fails, the app might not mount, resulting in a blank page or a white screen.

Q: How can I prevent stale chunks in the future?
A: Use content hashing in filenames, set proper cache headers (no-cache for HTML, immutable for hashed assets), and consider implementing a version check that forces a refresh when a new build is detected.

Q: Is a stale chunk the same as a browser cache issue?
A: Not exactly. A stale chunk is a specific case where the browser has an old version of a JS file that no longer matches the server’s current code. It’s a cache issue, but not all cache issues are stale chunks.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →