Guide · service-worker updates · 28 Sep 2026
Why a service-worker update can leave old assets in use
A new worker release does not replace JavaScript already running in an open page, rewrite that page's asset URLs, or clear Cache Storage.
The short answer
A browser must discover a changed worker, install it successfully, and activate it before it becomes the registration's active worker. With an existing active worker, a successful candidate normally waits until clients using the old registration unload and its old worker has no pending events. The previous worker remains active if candidate installation fails.
skipWaiting() asks a waiting worker to bypass the normal client-drain wait. Activation changes the controller of pages already using that registration; it does not reload them or replace their in-memory code. clients.claim() is a separate action: an active worker can take control of eligible matching pages that are not already using the registration.
Worker update and activation do not automatically change or delete named Cache Storage entries. Keep old fingerprinted assets and old cache entries while a supported old page or worker may still request them. Remove them only under an explicit compatibility and retention rule.
Use a compatible rollout
- Publish new fingerprinted files before HTML or a worker that references them. Keep old URLs available during the supported old-client window.
- Install into a new, versioned cache. Do not delete the prior cache during installation. If required installation work fails, let the candidate fail instead of activating an incomplete shell.
- Make the new worker route the new asset URLs deliberately. Give mutable HTML an explicit online revalidation and offline fallback policy.
- Let old pages drain by default. Detect a waiting worker and show an update notice; the platform does not provide this application UI.
- Offer reload at a safe boundary after saving work or reaching an app-defined idle point. Use forced activation only when old page code remains compatible or the application coordinates client state and reload.
- Retire old caches and server files only when the compatibility rule says supported old clients cannot need them. A visible client list at one instant is not a proof that no old request can arrive later.
These are application and deployment recommendations, not a platform-mandated cache strategy. Actual compatibility and the safe retention window are unknown without the target application's versions and support policy.
Record these facts before clearing anything
- Page and controller: record the page's embedded build marker; registration scope and installing/waiting/active script URLs and states; and
navigator.serviceWorker.controller?.scriptURL. The registration's active worker and one page's controller answer different questions. - Request: capture the exact asset URL/hash, initiator, whether a new request occurred, response body/build marker, and whether history or back-forward cache restored the document.
- Worker choice: log the worker build marker, request URL, Cache Storage name, match or miss, and whether the handler returned a cached response or delegated to
fetch(). A delegated fetch does not prove that the origin received the request. - Next hop: correlate request and response markers with a named intermediary record and, when available, an origin log or counter. Inspect browser HTTP cache and intermediary behavior separately.
Do not infer cause from a visible Cache Storage entry, a DevTools “from service worker” label, an active-registration field, a downloaded worker script, or an absent origin hit alone.
Expected behavior, not a tested deployment
The full dated report separates specified lifecycle transitions from browser guidance, lists expected but unexecuted synthetic scenarios, and marks the app compatibility and retention questions as unknown. No observed lifecycle, browser result, live cache result, analytics, or source attribution is claimed.
Related diagnosis
This report covers worker state and script-managed assets only. For the generic multi-hop procedure, use Locating the serving layer and the serving-layer diagnosis guide. For deployment and provider purge boundaries, see the deployment and incident runbook. For HTTP freshness and stale response rules, see When stale HTTP content is allowed.