MSW cannot register its worker because the script comes back as HTML
Failed to register a ServiceWorker for scope ('https://example.github.io/my-repo/') with script ('https://example.github.io/mockServiceWorker.js'): The script has an unsupported MIME type ('text/html').Short answer
The browser asked for mockServiceWorker.js and got an HTML page, so it refused to register it as a worker. Either the file was never generated into your public folder, or your site lives under a sub-path such as /my-repo/ while MSW still asks the domain root. Fix it with msw init and the serviceWorker.url option of worker.start().
Fix it fast
1Find out which cause you have
Open the worker address in a browser tab and look at what the server sends. A JavaScript file means the problem is elsewhere; an HTML page, a 404 or your app's own index means one of the causes below.
curl -i https://example.github.io/my-repo/mockServiceWorker.js2Match what you see, then jump to its fix
- 1
The address returns a 404 page or your app's HTML instead of a scriptThe worker file was never generated into the public folderFix - 2
The error shows the script at the domain root (/mockServiceWorker.js) while the page is under /my-repo/The site is served from a sub-path, but MSW asks the domain rootFix - 3
The registration works on the home page but fails after you open a nested route directly, such as /products/42The worker URL is relative, so client-side routes change itFix
- 1
What does the error look like?
Failed to register a ServiceWorker for scope ('https://example.github.io/my-repo/') with script ('https://example.github.io/mockServiceWorker.js'): The script has an unsupported MIME type ('text/html').
Cause 1 of 3
The worker file was never generated into the public folder
1Check
The init command copies mockServiceWorker.js into the folder your app serves as static files. If that step was skipped, or run for a different folder than the one your build copies to the output, the file is absent from the deployed site and the host answers with an HTML page.
ls public/mockServiceWorker.js
ls dist/mockServiceWorker.js2Fix
Run the init command for the static folder your build copies to the output. If the address still fails, the docs say to check that the folder is the right one and look at your static file configuration.
npx msw init public/ --save3Verify
Start the dev server and open the worker address. You should see the script text, and the console should print [MSW] Mocking enabled.
curl -I http://localhost:5173/mockServiceWorker.jsConfirmed by mswjs.io
Cause 2 of 3
The site is served from a sub-path, but MSW asks the domain root
1Check
By default MSW registers the worker from /mockServiceWorker.js, a path from the server root. A project page on GitHub Pages lives under /my-repo/, so that request lands outside your app and returns the host's HTML page.
curl -sI https://example.github.io/mockServiceWorker.js | head -n 5
curl -sI https://example.github.io/my-repo/mockServiceWorker.js | head -n 52Fix
Tell MSW where the file really is with the serviceWorker.url option. Keep the file at the base path of the app, because a worker can only control pages at its own location and below.
await worker.start({
serviceWorker: {
url: '/my-repo/mockServiceWorker.js',
},
});3Verify
Reload the deployed page with the console open. The registration error is gone and MSW logs that mocking is enabled.
curl -I https://example.github.io/my-repo/mockServiceWorker.jsConfirmed by mswjs.io
Cause 3 of 3
The worker URL is relative, so client-side routes change it
1Check
A relative script URL is resolved against the page that calls register(). On /products/42 a value like mockServiceWorker.js points to /products/mockServiceWorker.js, which your router answers with the app's HTML.
grep -rn "mockServiceWorker" src2Fix
Use a URL that starts with a slash and includes your base path, as in the previous cause.
await worker.start({
serviceWorker: { url: '/my-repo/mockServiceWorker.js' },
});3Verify
Open a nested route directly, then reload it, and check the console.
curl -I https://example.github.io/my-repo/mockServiceWorker.jsConfirmed by developer.mozilla.org
How do I stop it coming back?
- Keep mockServiceWorker.js in the static folder that your build copies to the output, and check it after the first deploy.
- Await worker.start() before the first render, as the MSW docs advise, so early requests are not sent before the worker is ready.
- After each deploy, open the worker URL once and confirm it returns JavaScript.
- Decide per environment whether mocks should run in a deployed build at all, and start the worker only where you want it.
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.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Service worker registration fails because the script comes back as HTML
The script has an unsupported MIME type (text/html)
The browser fetched your service worker URL and got a response that is not a JavaScript file.
2 causes, each with a fixWeb apps
React Router routes return 404 or a blank page on GitHub Pages
Blank page on https://user.github.io/repo-name/ and 404 for the JS and CSS files in the browser network tab
GitHub Pages serves files, so a deep link such as /about has no file and returns 404 before React Router runs.
2 causes, each with a fixWeb apps
Module not found for antd/dist/antd.less after upgrading to Ant Design 5
Module not found: Error: Can't resolve 'antd/dist/antd.less'
Ant Design 5 dropped Less and the bundled CSS file for CSS-in-JS, so antd/dist/antd.less no longer exists.
3 causes, each with a fixWeb apps
Astro Code component fails inside a React component
Astro components cannot be rendered directly via function call
Astro components such as Code only exist on the server and render static HTML.
2 causes, each with a fixWeb 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
How to catch and handle a 422 from Axios in a Redux thunk
action.error.message is 'Rejected' and action.payload is undefined
A 422 means the server read the request but cannot process its content, so repeating it unchanged fails again.
4 causes, each with a fix