Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

MSW cannot register its worker because the script comes back as HTML

ErrorFailed 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().

  • Applies to msw 2, React 19, GitHub Pages
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.js
  2. 2Match what you see, then jump to its fix

    1. 1The address returns a 404 page or your app's HTML instead of a scriptThe worker file was never generated into the public folderFix
    2. 2The 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. 3The 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

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.js

2Fix

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/ --save

3Verify

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.js

Confirmed by mswjs.io

Did this fix it?

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 5

2Fix

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.js

Confirmed by mswjs.io

Did this fix it?

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" src

2Fix

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.js

Confirmed by developer.mozilla.org

Did this fix it?

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:

Related fixes

Web 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.