MSW stops handling requests after 5 mins in page hidden state

[psea]

Prerequisites

• I confirm my issue is not in the opened issues
• I confirm the Frequently Asked Questions didn't contain the answer to my issue

Environment check

• I'm using the latest msw version
• I'm using Node.js version 20 or higher

Browsers

Chromium (Chrome, Brave, etc.)

Reproduction repository

https://github.com/psea/msw-hidden-timeout

Reproduction steps

Test app with steps to reproduce is deployed here:
https://psea.github.io/msw-hidden-timeout/

1. ✅ Check the status of the MSW. See the response.
2. ⚠️ Close developer tools if open.
3. 💤 Minimize the window or switch the tab.
4. ⏳ Wait 5 min before restoring the window.
5. ❌ Check the status of the MSW again. See the error.
6. ⛑️ Click the "🔧 Fix MSW" button to restore the mocking.
7. ✅ Check the status of the MSW again. See the response restored.

Current behavior

MSW stops handling requests after page is in a hidden state for 5 min.

Expected behavior

MSW continue handling requests after page become visible.

Related

Duplicate of #2115

[kettanaito]

Hi, @psea.

As you've discovered, this is likely caused by your browser's inactivity policy transitioning the worker into the idle phase where it cannot affect requests on the page anymore until explicit user action. Does refreshing the page after MSW stopped working help? I believe it should.

We can, technically, detect this particular scenario with the visibilitychange listener, then check if the page is controlled, and refresh it for you if it's not. The only potential problem here is that in case of general (non-hidden) inactivity, the browser was not communicating that the service worker has stopped controlling the page. navigator.controller was set, everything was functioning as expected as far as JavaScript is concerned.

The inactivity behavior is proprietary and implemented on the browser's whim, which makes it hard to predict and deal with.

[psea]

Does refreshing the page after MSW stopped working help? I believe it should.

Yes, refreshing the page works. But that is quite abrupt thing to do. Let's say we have some in-memory state - think of React's useState - where we hold some app intermediate data, a half-filled form or something like that. Refreshing the page on visibility change to non-hidden will cause to loose that state. So for every tab switch, the app's state will be destroyed.

There is a softer workaround, it is to send MOCK_ACTIVATE message navigator.serviceWorker.controller.postMessage("MOCK_ACTIVATE"). That is what "Fix MSW" button does in the test app.
That message will restore internal state of MSW worker - the activeClientIds set. I wonder if instead app messes with MSW internals, like sending MOCK_ACTIVATE messages, it could be solved by MSW library itself.

That is what I believe is happening.
Chrome terminates the worker after a period of inactivity (30sec seems to). To mitigate that MSW sends keep-alive messages on 5s intervals. Thus the worker should never be terminated while keep-alive messages flowing. But these keep-alive messages do not work well when page is hidden. After page being hidden for some time, Chrome throttles timers to fire once per minute. Hence keep-alive messages will be send only every minute, that is enough of interval for Chrome to terminate the worker. When incoming keep-alive message will come, Chrome will revive the dormant worker, but it's internal state will be lost - the activeClientIds set will be empty. Subsequently, all further fetch messages will be ignored, the MSW worker will think there are no active clients.
Manually sending the MOCK_ACTIVATE will restore the MSW internal state - it adds a client to activeClientIds.
To summarize, in Chrome the keep-alive feature only works when page is visible.

While we totally can solve it on the application side, by sending the MOCK_ACTIVATE message at appropriate time. There are a few issues with that. First, we rely on internal detail of MSW - MOCK_ACTIVATE message. I guess it's not in it's public API surface. Second, if worker receives the fetch message while it is dormant it will be unhandled. The worker will still be activated at that time, but it's activeClientIds will be empty. Those unhandled request responses will be cached by fetching library, showing user an error until MOCK_ACTIVATE is send and refetch will be made.

I wonder if there is anything we can do here? Either to have keep-alive messages work in page hidden state to prevent worker termination and loosing worker state (activeClientIds set). Or maybe somehow made MSW service worker resilient against termination. Otherwise the scenarios when you switch away from the tab and come back later will not work.

P.S. Thanks for maintaining that awesome project. It's delightful to use it! ❤️

[kettanaito]

Appreciate your taking some time to look into this. It's a bit more finneky since this browser behavior is non-standard and very likely changes between releases (I recall the inactivity policy being 5 minutes, then more, now you claim it's sub 1 minute...).

The worst part here is that the browser doesn't notify the app/worker that it's been "waked". So while you can send another MOCK_ACTIVATE via a button, you can recover because you know you have to recover right now. The library doesn't. Hence the whole difficulty of making the recovery smooth.

While we totally can solve it on the application side, by sending the MOCK_ACTIVATE message at appropriate time.

This is most certainly the wrong layer to address this issue.

I wonder if there is anything we can do here? Either to have keep-alive messages work in page hidden state to prevent worker termination and loosing worker state (activeClientIds set)

The worker state is lost because the browser deactivates the worker (i.e. unregisters it). So, in a way, empty activeClientIds is correct—the worker isn't aware of any controlled clients because no clients have sent MOCK_ACTIVATE again (library-specific behavior).

What can we do?

The perfect fix is to see if we can derive the "wake up" state by anything that happens to the worker. Does the browser fire the statechange event on the worker? It should, but, again, this whole flow is undocumented so I won't be surprised if it doesn't. We could listen to the worker state change and if it transitions from inactive to active, send MOCK_ACTIVATE from the client again. That is if the browser actually notifies us about this change.

If it doesn't, there's little we can reliably do.

As I mentioned, we can just detect page visibility change and fire MOCK_ACTIVATE preventively..? Not perfect but would recover from your particular case. I really dislike solving specific cases instead of addressing the behavior at its root, but it seems we are where we are.

I can raise this with the Chromium maintainers to learn more about this behavior. Maybe there's an escape hatch.

[psea]

Does the browser fire the statechange event on the worker?

No, it doesn't as far as I can see. I'm listening to statechange event in the test app, but can not see it firing. That Chrome behavior is a bit bonkers. Chrome terminates the worker at will, then restores it on an incoming event but with all global variables lost. And provide no way for us to know it just did it. They probably had their reasons but it's really hard to justify from the application developer point of view. 😞

As I mentioned, we can just detect page visibility change and fire MOCK_ACTIVATE preventively..?

Yes, that's what I end up doing. Send MOCK_ACTIVATE preemptively on visibility change and before each fetch call.

[kettanaito]

I can sort of get by sending MOCK_ACTIVATE on visibility change, but I'm still not convinced this is the right way to address this issue. But if visibility change fix helps, that's not such a bad thing, given we don't produce confusing console messages (activation should run in the background).

This won't be bullet-proof. If you've got some polling going on, there will be requests that will fail, even when we restore the worker after visibility change. There's always the window that the client-worker messaging takes.

[psea]

If you've got some polling going on, there will be requests that will fail, even when we restore the worker after visibility change.

Yes, I do polling. It is the reason I end up sending MOCK_ACTIVATE before each fetch call. Same as @jkinger did in the previous issue #2115 (comment)

[psea]

As an experiment, if I patch mockServiceWorker.js to ignore the activeClientsIds completely and instead always use self.clients.matchAll()[0] as a client everywhere, it makes it work perfectly with my one and only client.
Of course it's not the solution, but it makes me think if maybe there is a way to make worker resilient against termination by making it not to rely on global variables? I guess that's what Chrome advises to do 🤷‍♂️ ? After all the self.clients always contains all the clients.

[firasrg]

Hello everyone! This issue was super annoying, it caused the same bug report 5 times after deployment (in company where I work). I tried many approaches before landing on this solution that finally solved it reliably.

My main.tsx file

async function enableMocking() {
  if (import.meta.env.VITE_ENABLE_MOCK === "true") {
    try {
      const { worker, setWorkerReady, setupServiceWorkerHandlers } =
        await import("./mocks/browser");

      console.log("[App] Step 0: Configuring MSW handlers...");
      setupServiceWorkerHandlers();

      console.log("[App] Step 1: Starting MSW worker...");
      const startPromise = worker.start({
        serviceWorker: {
          url: "/mockServiceWorker.js",
          options: {
            scope: "/",
          },
        },
        onUnhandledRequest: (request, print) => {
          const url = new URL(request.url);

          if (
            !url.pathname.includes("/assets/") &&
            !url.pathname.includes("/public/") &&
            !url.pathname.includes("/@") &&
            !url.pathname.endsWith(".js") &&
            !url.pathname.endsWith(".css") &&
            !url.pathname.endsWith(".html") &&
            !url.pathname.endsWith(".png") &&
            !url.pathname.endsWith(".svg") &&
            !url.pathname.endsWith(".ico")
          ) {
            console.warn(
              `[MSW] ⚠️ Unhandled ${request.method} ${url.pathname}${url.search}`
            );
            print.warning();
          }
        },
        quiet: false,
      });

      const timeoutPromise = new Promise((_, reject) =>
        setTimeout(() => {
          reject(new Error("MSW worker startup timeout (>10s)"));
        }, 10000)
      );

      await Promise.race([startPromise, timeoutPromise]);

      setWorkerReady();

      console.log("[App] ✅ MSW Worker is fully initialized and ready");
      if ("serviceWorker" in navigator) {
        const registration = await navigator.serviceWorker.getRegistration();
        if (registration?.active) {
          console.log("[App] ✅ Service Worker is active and registered");
          registration.active.postMessage("MOCK_ACTIVATE");
          console.log("[App] ✅ Sent MOCK_ACTIVATE to service worker");
        } else {
          console.warn(
            "[App] ⚠️ Service Worker registration found but not active"
          );
        }
      }

      window.addEventListener("online", () => {
        console.log("[App] Network online - MSW should still be working");
      });

      window.addEventListener("offline", () => {
        console.warn(
          "[App] Network offline - but MSW should still work locally"
        );
      });
    } catch (error) {
      console.error("[App] ❌ CRITICAL: MSW initialization failed!", error);
      console.error(
        "[App] The app will run without mocking - API calls will fail"
      );
      // Show error to user in production
      if (!import.meta.env.DEV) {
        alert("Failed to initialize demo mode. Please refresh the page.");
      }
    }
  }
}

Then I use this function as follows :

enableMocking()
  .then(() => {
    ReactDOM.createRoot(rootElement).render(
      <React.StrictMode>
            <App />
      </React.StrictMode>
    );
  })
  .catch((error) => {
    console.error("[App] Failed to initialize:", error);
  });

My Workaround file browser.ts

This file holds the functions used in my main.tsx > enableMocking api :

import { setupWorker } from "msw/browser";
import { handlers } from "./handlers";

export const worker = setupWorker(...handlers);

console.log( `[MSW] 📋 Registered ${handlers.length} handlers at initialization`);

worker.events.on("request:start", ({ request }) => {
  const url = new URL(request.url);
  console.log(`[MSW] 🟢 Request START: ${request.method} ${url.pathname}`);
});

worker.events.on("request:match", ({ request }) => {
  const url = new URL(request.url);
  console.log(`[MSW] ✅ Request MATCHED: ${request.method} ${url.pathname}`);
});

worker.events.on("request:unhandled", ({ request }) => {
  const url = new URL(request.url);
  if (
    !url.pathname.includes("/assets/") &&
    !url.pathname.includes("/public/") &&
    !url.pathname.endsWith(".js") &&
    !url.pathname.endsWith(".css") &&
    !url.pathname.endsWith(".html") &&
    !url.pathname.endsWith(".png") &&
    !url.pathname.endsWith(".svg") &&
    !url.pathname.includes("/@")
  ) {
    console.warn(
      `[MSW] ⚠️ Request UNHANDLED: ${request.method} ${url.pathname}`
    );
  }
});

worker.events.on("response:mocked", ({ request, response }) => {
  const url = new URL(request.url);
  console.log(
    `[MSW] 📤 Response MOCKED: ${request.method} ${url.pathname} → ${response.status}`
  );
});

worker.events.on("response:bypass", ({ request }) => {
  const url = new URL(request.url);
  console.log(`[MSW] ⏩ Response BYPASS: ${request.method} ${url.pathname}`);
});
console.log("[MSW] ✅ Event listeners registered");

let workerReady = false;
let keepaliveInterval: number | null = null;

export const isWorkerReady = (): boolean => workerReady;

export const setWorkerReady = () => {
  workerReady = true;
  console.log("[MSW] ✅ Worker is ready and listening for requests");
  startKeepalive();
};

const startKeepalive = () => {
  if (keepaliveInterval) {
    clearInterval(keepaliveInterval);
  }

  keepaliveInterval = window.setInterval(() => {
    if ("serviceWorker" in navigator && navigator.serviceWorker.controller) {
      navigator.serviceWorker.controller.postMessage("KEEPALIVE_REQUEST");
    }
  }, 25000);
  console.log("[MSW] ✅ Keepalive mechanism started (25s interval)");
};

export const setupServiceWorkerHandlers = () => {
  if (!("serviceWorker" in navigator)) return;

  navigator.serviceWorker.addEventListener("controllerchange", () => {
    console.log("[MSW] ⚠️ Service worker updated - reloading page...");
    window.location.reload();
  });

  navigator.serviceWorker.addEventListener("message", (event) => {
    if (event.data?.type === "KEEPALIVE_RESPONSE") {
      console.log("[MSW] ⚠️ Keepalive received - worker is alive");
    }
  });

  setInterval(() => {
    navigator.serviceWorker
      .getRegistration()
      .then((registration) => {
        registration?.update().catch(() => { /* ignore update errors */});
      })
      .catch(() => {/* ignore registration errors */});
  }, 60000); // Check every minute

  document.addEventListener("visibilitychange", async () => {
    if (document.visibilityState === "visible") {
      console.log("[MSW] Tab became visible - checking connection...");

      const registration = await navigator.serviceWorker.getRegistration();
      if (!registration?.active) {
        console.error("[MSW] ❌ Service worker lost - reloading page...");
        window.location.reload();
        return;
      }

      if (navigator.serviceWorker.controller) {
        navigator.serviceWorker.controller.postMessage("KEEPALIVE_REQUEST");
      } else {
        console.error("[MSW] ❌ No controller - reloading page...");
        window.location.reload();
        return;
      }

      if (!keepaliveInterval) {
        startKeepalive();
      }

      if (registration.active) {
        registration.active.postMessage("MOCK_ACTIVATE");
        console.log("[MSW] ✅ Re-activated MSW after visibility change");
      }
    }
  });
  console.log("[MSW] ✅ Service worker lifecycle handlers configured");
};

export const getWorkerStatus = () => {
  const activeHandlers = worker.listHandlers();
  return {
    isReady: isWorkerReady(),
    keepaliveActive: keepaliveInterval !== null,
    handlersCount: handlers.length,
    activeHandlersCount: activeHandlers.length,
  };
};

I know it’s a bit long, but I wanted to include everything to help as much as possible

[kettanaito]

it makes me think if maybe there is a way to make worker resilient against termination by making it not to rely on global variables?

There's nothing wrong with introducing state in the worker. If anything, the browser shouldn't reset that state as a part of waking up the worker. But since this behavior is not in the spec and is entirely up to the browser to decide, we are chasing whims at this point.

After all the self.clients always contains all the clients.

You seem to be under an incorrect assumption that activeClientIds is the same as self.clients. We aren't duplicating the data here. activeClientIds, as the name suggests, is a subset of self.clients and contains IDs for the clients that have mocking enabled. Any client can disable the mocking by calling worker.stop(). That doesn't unregister the worker since (1) that's destructive to other clients that expect mocking to work; (2) unregister/register roundtrips are expensive.

@firasrg, thank you for sharing our findings! I appreciate the level of detail, but it makes it hard to figure out what exactly you did that solved the issue for you. Can you please write a short summary or, even better, share a diff?

The same for the added logs: which fire? In which order? A list/screenshot would be most welcome.

[kettanaito]

The root cause here is that the browser transitioning the worker to the inactive state is a proprietary browser behavior not describe in the Service Worker specification. On top of that, the browser doesn't actually fire statechange nor controllerchange on the worker/controller for the client to react when that happens (at least, from my previous observations; happy to be proven wrong here).

With that in mind, I don't see a proper fix here. The browser doesn't give us any means to react to this behavior occurring to provision any sort of recovery mechanism. The fact that it tears down the worker and reinstates is again without controllerchange is just sad.

Any approach on our end means losing the activeClientIds state. So the clients that had mocking disabled will have it enabled after the worker wakes up. This is annoying and undoes the user actions.

I'm starting to think that the "fix" here is to force a page reload instead, forcing the client-worker to go through their regular messaging. But without a reliable trigger for reload, we might as well be introducing a new issue on top.

[kettanaito]

The actual viable solution here might be raising a bug in Chromium and trying to persuade the team to adhere to the spec and fire events on the worker/controller for this behavior. It's wild if they aren't doing that.

[kettanaito]

Proposal

We can also move activeClientIds from the worker to a layer shared between the worker and the client. Something like caches. What this will change:

• The worker becomes stateless. Adding/removing/idling it won't disrupt anything.
• The client can add/remove itself from the active clients via caches directly, which is potentially cheaper than going through the messaging roundtrip.

I think I like this one the most. Not sure if the CacheStorage is the best choice for that shared layer, given it operates on requests/responses and it will be clunky to store a response whereas all we care about is a set of values.

The downside here is that tapping into that layer will be expensive. The state changes at a fixed time (worker.start(), worker.stop()), but the worker has to pay the cost of checking it on every request, which is suboptimal. I guess we can optimize that by opening the cache at the root scope and then only matching in the fetch listener.

const clientsCache = await caches.open('clients-cache')

addEventListener('fetch', async () => {
  const activeClientIds = await clientsCache.match(...)
})

This should minimize the performance impact. After all, read/write from cache is what service workers are designed to do. What remains is the clunky part of serializing the clients set in a Response that gets stored in cache.