Module Federation app crashes on start with 'Shared module is not available for eager consumption'
Uncaught Error: Shared module is not available for eager consumptionShort answer
Module Federation fills the shared scope (react, react-dom) asynchronously. If your entry file imports React straight away, the code runs before that scope is ready and throws. Move the startup code into a bootstrap file and load it with a dynamic import(). Use eager: true on the shared module only when you cannot change the entry.
Fix it fast
1Find out which cause you have
Open the file that is the webpack entry (usually src/index.js) and check whether it imports React, ReactDOM or your App at the top level. If it does, the first cause below applies.
grep -n "entry" webpack.config.js head -20 src/index.js2Match what you see, then jump to its fix
- 1
The error appears in the browser console on page load, and the stack points at the entry chunk (main.js or index.js).The entry file runs synchronously, with no async boundaryFix - 2
The entry file is generated or owned by something else (a shell or a template), and the error names one specific shared package such as react.You cannot add a boundary to this entry, so the shared module must be provided eagerlyFix
- 1
What does the error look like?
Uncaught Error: Shared module is not available for eager consumptionShared module is not available for eager consumption: webpack/sharing/consume/default/react/react
Cause 1 of 2
The entry file runs synchronously, with no async boundary
1Check
Look at the entry file. If it has static imports such as react-dom/client and ./App and calls createRoot straight away, the shared modules are requested before the share scope has been initialised.
cat src/index.js2Fix
Make the entry a one-line dynamic import and move the old startup code into a new file called bootstrap.js. The dynamic import creates the async boundary that gives Module Federation time to set up the shared scope.
// src/index.js
import('./bootstrap');
// src/bootstrap.js
import { createRoot } from 'react-dom/client';
import App from './App';
const root = createRoot(document.getElementById('root'));
root.render(<App />);3Verify
Rebuild and reload the page. The console error is gone and the app renders.
npx webpack serveConfirmed by webpack.js.org
Cause 2 of 2
You cannot add a boundary to this entry, so the shared module must be provided eagerly
1Check
Look at the shared option of ModuleFederationPlugin. A shared module that is not eager is delivered through an asynchronous request, which an eagerly executed entry cannot wait for.
grep -n -A8 "shared" webpack.config.js2Fix
Mark the dependency as eager in the advanced shared syntax. The webpack docs say to do this in one place only, for example the shell, because eager modules and their fallbacks are always downloaded. The async bootstrap from the first cause is the recommended fix.
new ModuleFederationPlugin({
shared: {
...deps,
react: {
eager: true,
},
},
});3Verify
Rebuild the shell and reload. The error no longer appears for that package.
npx webpackConfirmed by webpack.js.org
How do I stop it coming back?
- Start every Module Federation app and remote from a tiny index file that only does import('./bootstrap').
- Share react and react-dom with singleton: true so only one copy runs on the page.
- Use eager: true in a single place only, because its modules are always downloaded.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fixWeb apps
Axios returns 401 from a React app but the login works elsewhere
Error: Request failed with status code 401
A 401 means the server received the request without valid credentials.
3 causes, each with a fixWeb apps
An axios call never finishes when the API server stops answering
code: 'ECONNABORTED'
Axios has no timeout unless you give it one: the default is 0, which means wait forever.
3 causes, each with a fix