The way React, Vue, Angular and similar frameworks work is by downloading JavaScript files and using them to render websites on the browser. Whenever a project is built, two types of files are created:
- Main entry file - The file to which the script tag in index.html points to
- Other helper files - The files which are imported by the main entry file whenever required.
Most of the time, if you have a small project, a single entry file is enough. You can store all the JavaScript code into the same file. But, for faster loading and better user experience, the JavaScript code can also be broken down into multiple files when it's built and these files are dynamically fetched by the main entry file whenever required.
Now, whenever there’s an error observed in fetching these other helper JavaScript files, a ChunkLoad Error is thrown. The multiple JavaScript files used are also known as chunks, and hence the name of the error.
What Causes the Chunk Load Error?
To recap, the Chunk Load Error occurs when the browser encounters an error in fetching some JavaScript files, which were dynamically imported. There’s a couple reasons you may have encountered this error:
The checksum validation for the JavaScript file failed
This can occur when the checksum of the received file does not match the integrity attribute of the script tag. (For more information on why this is important and how it’s done you can refer to Subresource Integrity - Web security | MDN). A possible reason for this is that you have antivirus, browser extensions, proxies, or ad blocking software that may be modifying the file contents, resulting in it not matching the checksum.
The relevant chunk files can not be found or are outdated
Again, this can occur because your browser is not able to find and/or download the chunk file, maybe because the file does not exist, but also because of the hundreds of reasons for internet failure (proxies, firewalls, outages etc.). It can also occur if the browser is able to download the chunk file, but the downloaded file is an outdated one.
Example of the Chunk Load Error
Assume a user is using your app, he has downloaded the main entrypoint file which is, in turn, going to download chunk1.js, chunk2.js, chunk3.js, … whenever required. At the same time, you push a critical bug fix and redeploy the application.
This causes the previous chunks to be deleted and be replaced by new ones, say chunkA.js, chunkB.js, chunkC.js, … Now for the user, whenever his entrypoint file tries to download the file chunk2.js it’ll give a chunk load error since the file does not exist.
An extension of this use case is when, due to some caching in between the user and your server, the user is served an older entrypoint file, even though you’ve redeployed the application long back. This causes the browser to try and fetch older non-existent files, resulting in a Chunk Load Error.
Reproducing the Error
You are most likely already stuck on this error, but here’s a simple way to reproduce the Chunk Load Error.
Let’s say you have a App.jsx which looks like this
import React, { Suspense } from 'react';
const OtherComponent = React.lazy(() => import('./OtherComponent'));
const App = () => {
return (
<h1>
<Suspense fallback={<div>Loading...</div>}>
<OtherComponent />
</Suspense>
</h1>
);
};
export default App;
And an OtherComponent.jsx which contains -
const OtherComponent = () => {
return (
<div>
Hello World
</div>
);
};
export default OtherComponent;
Building this project should create multiple chunks, which you can see in your build folder. You can now serve this build folder, and delete one of the chunks created. Now, since the browser is trying to fetch a chunk, but is unable to fetch it since it doesn’t exist, it’ll throw a chunk load error.
How to Fix Chunk Load Error
As a user
If you are encountering this error as a user of an application, the most simple way to resolve it is to clear your browser cache (and also restart it for good measure) and try again. If the error was because your browser had cached older files, this should fix the issue. But if the problem is due to the chunk files, there’s nothing you can do except alert the application developers and wait till the problem has been fixed.
As a developer
Since the most common occurrence of this error is when the chunk files are missing, you can start by ensuring that the chunk files are being correctly served, and the URLs being used to download the chunk files are appropriate.
If you observe that the files are not being served correctly or the URLs are incorrect, it should be straightforward to resolve this problem so that the files are being served accurately. This should solve the Chunk Load Problem as well. Since there are a plethora of tools used to serve these files, we’ve not covered how to solve the file serving problem in this tutorial, but it should be fairly easy.
Apart from this, if you are part of a team that does frequent deployments, and you’ve been getting complaints that users are facing this error, it’s because of the example we discussed above - the users are using your application when you deploy.
A simple fix to this is to ensure that whenever you deploy a newer version, you continue serving the older files for users who have the older entrypoint files downloaded. This way they can still continue using your application, albeit with the older files, for the current session. Whenever they refresh the page, the latest entrypoint will be downloaded and they’ll automatically be shifted to the newer version.
Along with this approach, it’s also a good idea to have your index.html and entrypoint files never cached, which can be done using the cache-control header (Cache-Control - HTTP | MDN)
Other workarounds
The above techniques should work for 99% of the applications, but if you are working on a crucial application that requires users should always be served with the latest version and should encounter no downtime, there are some advanced techniques you can use to ensure your users don’t face a Chunk Load Error. These are outside the scope of this article, but we’ll point links to it just in case.
- You can introduce an extra layer of abstraction to handle the exceptions, and ensure that the browser tries again after some time to fetch the chunk file. This approach along with the code has been beautifully explained by Tushar in his article React — Loading Chunk Failed Error | by Tushar Mohan
- Similarly, you can also force the user’s browser to hard reload the page and try again, which will help you get rid of the cache-caused Chunk Load errors. This can be done by using the lazyWithRetry function React LazyWithRetry · GitHub, instead of the default lazy function used in react.
Track, Analyze and Manage Errors With Rollbar
Managing errors and exceptions in your code is challenging. It can make deploying production code an unnerving experience. Being able to track, analyze, and manage errors in real-time can help you to proceed with more confidence. Rollbar automates error monitoring and triaging, making fixing JavaScript errors easier than ever. Try it today!
