A lazily loaded route's bundle request 404s for a user whose tab has been open since before a deploy. What happened, and how should the app recover?

## Why the request misses Builds usually publish bundle files under content-derived filenames, so a new build produces new filenames. A document that was loaded before a deploy carries the **old** build's filenames inside it. Its route table's loaders will ask for those exact files. If the deploy removed them, the request fails — a 404, or whatever the host serves for an unknown path, which may even be an HTML error page rather than a module. Nothing in the app is broken. The route table matched correctly, the params parsed, the navigation started; the only failure is that the artefact this document was built against no longer exists on the server. That is why the symptom is so specific: only users with long-open tabs see it, only on routes they had not yet visited in that tab, and it disappears the moment they reload. ## A load rejection is not a render error The component never ran. There is no bad state inside it to reset and no render to retry, so anything that merely re-renders the failed subtree changes nothing. Two consequences: - The recovery belongs at the route level, around the thing that owns the loader, not inside the screen that failed to appear. - A retry must **call the loader again** and issue a new request. If the router memoised the rejection, a retry is a no-op that replays the same failure — which is exactly why a resolved module is cached and a rejected one normally is not. ## Transient failure versus a removed artefact These look identical at the point of failure and need opposite responses. | | Transient network failure | Artefact removed by a deploy | |---|---|---| | Cause | offline, flaky link, timeout, server blip | the document references filenames that no longer exist | | Will a retry help? | yes, often on the first attempt | never, for this document | | Right response | retry, with a short backoff and a small cap | reload the document once, so the new build is fetched | | Wrong response | reload, losing the user's page state | retry forever and call it resilience | | Distinguishing hint | intermittent, may succeed on retry | deterministic for this tab, fine in a fresh one | You cannot always tell them apart from the failure alone, so the usual shape is: retry a small number of times first, and treat persistent failure as a possible stale document. ## The reload-once recovery 1. Catch the rejection at the route-level failure path. 2. Retry the loader once or twice with a short delay. If it succeeds, continue as normal; the user saw a brief pending state. 3. If it still fails, check a marker recorded for this document or session that says "a recovery reload has already been attempted for this URL". 4. If the marker is absent, set it and reload the document, ideally at the URL the user was navigating to so the reload lands where they wanted to go. 5. If the marker is present, do **not** reload. Show a failure state with an explicit retry the user controls, and report the failure. Step 5 is the whole point of the guard. Without it, a build that is genuinely broken for everyone turns into a reload loop: load, fail, reload, fail. A loop is worse than an error message, because the user cannot read anything and your own reporting drowns. ## Shrinking the window instead of only handling it - Keep the previous release's bundle files served for a while after a deploy rather than deleting them immediately. Old tabs then continue to work, and the failure becomes rare enough to be a genuine edge case. - Have the app notice that a new version is available and invite the user to reload at a moment of their choosing, so the stale document is replaced before it hits a missing file. - Deploy the new files before the document that references them, and remove old files last, so there is never a moment where a served document names a file that is not there. - Be aware that any local code cache the app itself owns can hold a stale document long after the server has moved on; that cache's own invalidation is a separate concern with its own rules. ## What the user should see Never a blank screen. Either the previous screen with a failure message and a retry control, or the route's failure state naming what happened in plain terms — something went wrong loading this page, try again — with the underlying cause reported for you rather than shown to them. And instrument it: a rising count of bundle-load failures immediately after each deploy is the signal that your artefact retention window is too short, which is a far better fix than better error copy.