angular.io app gets stuck in “loading document” state, likely due to client-server version skew

[IgorMinar]

On several occasions in the past I’ve observed that if I have a long running angular.io app open in a tab, and after some time I come back to this tab and try to use it for another navigation within the app, the app responds with doc viewer progress bar indicating the document is being loaded, but it never actually loads the doc and remains in this state forever. Reloading the page resolves the issue.

When I was looking through the Google Analytics (GA) data today, I noticed that there was a spike in errors just after the holidays:

Google Analytics report

Notice how the spike starts just around Jan 7 when most people got back from holidays, and relatively quickly things come back to normal within the next few days.

If we look into the error causes, you’ll see that the main root cause is failing to download certain JS chunks, mainly the “toc-module” chunk (there are some others if you go into the report and look at the long tail of errors, but they are less common).

This makes me believe that the problem I observed in the past and this error spike after holidays are related.

Here is my interpretation of the events:

• many people were on angular.io before holidays and visited only the home page but not any api/guide doc (the toc-module case), and others visited other pages as well and their case is captured in the long tail of errors other than “toc-module”.
• these people left their app open, then came back around Jan 7 and tried to use the app for a new navigation
• in the meantime we deployed many new versions of angular.io, changing the fingeprints of chunks
• when the new navigation occured in the long-running app, the app (webpack module loader) tried to download the chunk for the missing code (e.g. toc-module)
• the server however no longer hosted that chunk because we redeployed angular.io with new versions since then and returned 404
• it’s uncommon that we fail to load code in this way, so the app just paniced and got stuck in the “loading document” state.
• user had to reload the page to recover and since reloading helped, people just shrug and moved on without reporting the problem...

There are at least three problems we need to fix:

• the module loading errors should not cause the app to freak out, we should either display the snack bar telling the user that there was an error and they should try to reload, or we should consider reloading the page automatically (but ensure we don’t end up in an infinite loop of reloads if a reload doesn’t cause the app to recover)
• look into why “toc-module” fails so frequently and consider prefetching and caching it along with the main chunk
• we should somehow deal with the client-server version skew (have service-worker cache all chunks lazily, host old chunk versions, etc)

---

UPDATE(2021-09-20):
See #28114 (comment) for an explanation of the problem.

[fredsa]

Having the server keep old chunks for previously deployed versions could be part of the solution for angular.io, but this can't be what Angular relies on by default, as this would greatly complicate deployment of apps to hosting services that expect to be given all static content at each deployment.

Catching the error and providing a default message to end users that suggests reloading sounds pretty good. I'd add to that a hook, similar to the global handler, so devs can replace this message with their own handler code.

[petebacondarwin]

That is interesting analysis @IgorMinar - I agree that we should prompt the user with a better error. Also once we land this PR (#28037) that retains the current scroll position on reload, it would be much safer to do automatic reloads.

[manekinekko]

Interesting. Just an FYI, we have noticed a similar behavior with https://xlayers.app. This happens after each deployment.

[Brandinga]

just my observations:
in our production enviroment, this error also happens if old chunks are not deleted.
the error is mostly sent from the current version (i added a version number to each error log)
--> but i would expect, it is reported from old versions
--> i think the problem comes also from flaky internet connections
(i did not delete old chunks since July 2018, preloadingStrategy: PreloadAllModules, no service-worker configured)

Thanks for sharing this!

[gkalpak]

• the module loading errors should not cause the app to freak out, we should either display the snack bar telling the user that there was an error and they should try to reload, or we should consider reloading the page automatically (but ensure we don’t end up in an infinite loop of reloads if a reload doesn’t cause the app to recover)

I am not a big fun of auto-reloading, but +100 for doing a better job at notifying the user (right now the app gets stuck on a blank screen, which is 👎).

• look into why “toc-module” fails so frequently and consider prefetching and caching it along with the main chunk

I suspect that the reason this one fails much more often than others is that basically all docs (i.e. non-marketing pages) require the <aio-toc> element (while other chunks/custom elements are only required some of the time). Furthermore, on small screens (e.g. mobile) the <aio-toc> chunk - when needed - is requested earlier than others via AppComponent's template directly, so it is the first request to fail and cause the error.

As I've written elsewhere (see below), I still don't understand how this could be happening (although I may have some far-fetched theories), since to requested file is part of the eagerly cached app-shell asset group (see our ngsw.json). This is the same asset group that is theoretically serving the outdated index.html. (So, if the outdated index.html referencing the outdated chunks is still in the case, how come the chunks themselves aren't??? 😕)

• we should somehow deal with the client-server version skew (have service-worker cache all chunks lazily, host old chunk versions, etc)

I have looked into this errors before and haven't been able to figure out why they are happening (or even how are they possible), because the SW should have the necessary files in its cache 😒

Copying my comments from Slack (not public):

While it worked fine on my mobile, I got an error on my laptop:

Failed to load resource: the server responded with a status of 404 ()
main.c6614337f14ffce1caf6.js:1 ERROR Error: [DocViewer] Error preparing document 'api/core/IterableDifferFactory': Error: Loading chunk 12 failed.
(error: https://next.angular.io/toc-toc-module-ngfactory.d41e300812a73df91d75.js)
    at HTMLScriptElement.a (runtime.99ff37d281cef743f1d5.js:1)
    at HTMLScriptElement.D (zone.js.pre-build-optimizer.js:1188)
    at e.invokeTask (zone.js.pre-build-optimizer.js:421)
    at Object.onInvokeTask (main.c6614337f14ffce1caf6.js:1)
    at e.invokeTask (zone.js.pre-build-optimizer.js:420)
    at t.runTask (zone.js.pre-build-optimizer.js:188)
    at t.invokeTask [as invoke] (zone.js.pre-build-optimizer.js:496)
    at y (zone.js.pre-build-optimizer.js:1540)
    at HTMLScriptElement._ (zone.js.pre-build-optimizer.js:1566)
    at HTMLScriptElement.a (runtime.99ff37d281cef743f1d5.js:1)
    at HTMLScriptElement.D (zone.js.pre-build-optimizer.js:1188)
    at e.invokeTask (zone.js.pre-build-optimizer.js:421)
    at Object.onInvokeTask (main.c6614337f14ffce1caf6.js:1)
    at e.invokeTask (zone.js.pre-build-optimizer.js:420)
    at t.runTask (zone.js.pre-build-optimizer.js:188)
    at t.invokeTask [as invoke] (zone.js.pre-build-optimizer.js:496)
    at y (zone.js.pre-build-optimizer.js:1540)
    at HTMLScriptElement._ (zone.js.pre-build-optimizer.js:1566)
    at e.selector (main.c6614337f14ffce1caf6.js:1)
    at e.error (main.c6614337f14ffce1caf6.js:1)
    at e._error (main.c6614337f14ffce1caf6.js:1)
    at e.error (main.c6614337f14ffce1caf6.js:1)
    at e._error (main.c6614337f14ffce1caf6.js:1)
    at e.error (main.c6614337f14ffce1caf6.js:1)
    at e._error (main.c6614337f14ffce1caf6.js:1)
    at e.error (main.c6614337f14ffce1caf6.js:1)
    at e.notifyError (main.c6614337f14ffce1caf6.js:1)
    at e._error (main.c6614337f14ffce1caf6.js:1)
_r @ main.c6614337f14ffce1caf6.js:1
default~code-code-example-module-ngfactory~code-code-tabs-module-ngfactory.e903a21862713bcb7820.js:1 Failed to load resource: the server responded with a status of 404 ()

Opening the URL in a new tab worked fine.

AFAICT, some lazy-loaded files (i.e. custom elements) are mapped to versions (hashes) that are no longer deployed. In addition to that, the SW does not have these in the cache and tries to fetch them from the server (and fails).

Theoretically, the hashes (which are included in runtime.<hash>.js) should always be cached by the SW with the corresponding lazy-loaded JS files (since all are part of the eagerly fetched app-shell asset group).

So, if the SW serves an index.html, which contains a runtime.<hash>.js file that points to specific lazy-loaded JS files, it should also be able to serve those lazy-loaded files from the same cache.

I couldn't figure out under what circumstances this won't be true.

The only possible cause I can think of right now is having outdated index.html and runtime.<hash>.js served by the browser from the browser cache (not the SW cache), while the browser cache does not have lazy-loaded JS files.

I'll keep an eye for these errors and try to gether more info the next time, but - even if that was the case - it does not explain why it happened for some URLs on CI but not others.

Another possible explanation could be a bad CDN serving some outdated files but not others (but that sounds a little far-fetched) :thinking_face:

[juristr]

Just had the same issue opening the docs

[Toxicable]

Also had this issue and made a report here: #28243 (I didn't find this issues at the time)

[gkalpak]

Still not able to reproduce this reliably, but here is some more info:

This does not only happen when you have a tab open for a while. Yesterday, @benlesh run into it while having no tab open and by navigating to a docs page via a Google search results link 😞

Has anyone seen this in any other browser than Chrome?

[wKoza]

Yesterday, I have also had this error with a external link to the "next api" section ( I go seldom on this part). I had used Chrome.

[fredsa]

I only use Chrome and get this from time to time.

[IgorMinar]

Just happened again to me:

main.d6ed4a5a014b6cbb8d5f.js:1 ERROR Error: [DocViewer] Error preparing document 'cli/build': Error: Loading chunk 20 failed.
(error: https://angular.io/toc-toc-module-ngfactory.d0ce87256afe85686f1e.js)
    at HTMLScriptElement.a (runtime.60fab82dedf87ba383c8.js:1)
    at HTMLScriptElement.D (polyfills.a2efc1c1a62312ff1f80.js:1)
    at e.invokeTask (polyfills.a2efc1c1a62312ff1f80.js:1)
    at Object.onInvokeTask (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e.invokeTask (polyfills.a2efc1c1a62312ff1f80.js:1)
    at t.runTask (polyfills.a2efc1c1a62312ff1f80.js:1)
    at t.invokeTask [as invoke] (polyfills.a2efc1c1a62312ff1f80.js:1)
    at y (polyfills.a2efc1c1a62312ff1f80.js:1)
    at HTMLScriptElement._ (polyfills.a2efc1c1a62312ff1f80.js:1)
    at e.selector (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e.error (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e._error (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e.error (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e._error (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e.error (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e._error (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e.error (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e.notifyError (main.d6ed4a5a014b6cbb8d5f.js:1)
    at e._error (main.d6ed4a5a014b6cbb8d5f.js:1)

[manekinekko]

FYI, we had the same issue with 2 angular apps (https://xlayers.app) and (https://ngx.tools). Both apps are deployed to Firebase CDN. And this problem came from the default Firebase cache-control config. I had to temporarily disable the cache (no recommended of course):

"headers": [
      {
        "source": "/**",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "no-cache, no-store, must-revalidate"
          }
        ]
      }
    ]

I have tried other caching strategies but none worked.

[wKoza]

@manekinekko , you don't use webworker, do you ?

[manekinekko]

Nope, SW.

[gkalpak]

Interesting insight, @manekinekko.
@wKoza: I don't think webworker has anything to do with the problem. You probably meant serviceworker 😁 (AFAICT, ngx.tools does use a ServiceWorker and xlayers.app doesn't.)

[manekinekko]

@gkalpak xlayers.app used to have a SW but I had to disable it until I find a better solution for this caching issue.

[wKoza]

yes @gkalpak . It's hard this morning ;)

[gkalpak]

So, did the issue happen with the SW or also without?

[benlesh]

@gkalpak when you have a solution, can you please assist us in resolving this issue for RxJS docs? Since they're are fork of angular docs, they have the same issue. cc @niklas-wortmann

[gkalpak]

@benlesh, @niklas-wortmann: Sure, happy to help. The fix would be just updating to a version of @angular/service-worker that includes #43518 (once it is merged). No other change should be needed 🤞

[gkalpak]

@benlesh, @niklas-wortmann: FYI, the fix has been released in v12.2.8. So, you can update the docs app to that version to fix the issue.

[gkalpak]

Since both #43518 (which fixed the issue for @angular/service-worker) and #43687 (which updates angular.io to a version that includes the fix) have been merged, I am going to close this issue as "fixed" 🤞

Note that people might still see the issue one more time (i.e. the first time they visit angular.io since the fix was deployed), but the error rate should be dropping (and the data from Google analytics does confirm that). We'll keep an eye on this to make sure that the error rate continues to drop.

[petebacondarwin]

🎉 thank you @gkalpak for your determination and brilliance in finding a resolution to this really really annoying issue.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}