Debug a PWA

In one line: Chrome DevTools’ Application panel lets you inspect a PWA’s manifest, service worker state, and cached responses, and gives you controls to force an update, go offline, and bypass the service worker for the network.

The Manifest pane

Per Chrome’s documentation, DevTools → Application → Manifest displays the Identity and Presentation fields from the manifest “in a more user-friendly way,” shows every declared icon (with a checkbox to preview the safe area used by maskable icons), lets you test protocol handler registration, and — if DevTools finds a problem such as an icon that fails to load — shows an Installability section describing the error.

The Service Workers pane

Per Chrome’s documentation, this pane exposes several controls:

Control	What it does
Offline	Puts DevTools into offline mode
Update on reload	Forces the service worker to update on every page load
Bypass for network	Bypasses the service worker and forces the browser to the network
Update	Performs a one-time update of the specified service worker
Unregister	Unregisters the specified service worker
Push / Sync	Emulate a push event or a background sync event

The pane’s Status line reports the worker’s state and how many times it has updated; per Chrome’s documentation, if the worker throws errors, an error count appears next to the Source line instead.

// Feature-detect Service Worker support before relying on it.
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
} else {
  // Fallback: no Service Worker API — the app must work without one.
}

Cache Storage and Clear Storage

DevTools → Application → Cache Storage is a read-only list of everything stored via the service worker Cache API; some entries may show as “opaque” responses, which affects how their size counts against storage quota. Per Chrome’s documentation, DevTools might not initially detect a cache change — reload the page if a cache you expect to see doesn’t appear. The Clear Storage pane unregisters service workers and clears caches and storage with a single click — useful for resetting to a clean state between test runs.

Testing offline behaviour

Per Chrome’s documentation, the Offline checkbox in the Service Workers pane puts DevTools into offline mode and is equivalent to the offline mode in the Network panel. Per MDN’s PWA guidance, a service worker can intercept network requests and respond with a custom offline page instead of the browser’s generic error page — that is the behaviour to verify while Offline is checked.

Where it is supported

This guide documents Chrome DevTools specifically: the Manifest, Service Workers, and Cache Storage panes described above are Chrome’s own developer tools, per Chrome’s documentation. It does not cover Firefox’s, Safari’s, or any other browser’s developer tools — that is out of scope for this guide.

What goes wrong

• Update button vs. Update on reload: per Chrome’s documentation, “Update” performs a one-time update check, while “Update on reload” forces an update on every page load. Neither is a re-register control — if a worker looks stuck, the pane’s own controls are Update and Unregister; there is no separate “re-register” action.
• Worker stuck in “waiting”: per Chrome’s documentation, the update-cycle table in the Service Workers pane can show install, wait, and activate activity for a worker — use it to see which phase a worker is stuck in.
• Nothing shows in Cache Storage: per Chrome’s documentation, DevTools may not detect a cache change right away; reload the page before assuming the cache is genuinely empty.
• Offline fallback doesn’t appear: check the Service Workers pane’s error count next to the Source line — Chrome documents that service-worker errors surface there.

Practical checklist

• Check the Manifest pane’s Installability section for manifest/icon errors before debugging anything else.
• Use “Update on reload” during development to force an update check on every page load.
• Use “Bypass for network” to compare behaviour with and without the service worker in the loop.
• Use Clear Storage to reset service workers, caches, and storage between test runs.
• Verify the offline fallback with the Offline checkbox, and check the Service Workers pane’s error count next to the Source line if it doesn’t appear.

Where to go next

• Debugging service workers — more on inspecting service workers across browsers
• The update flow and skipWaiting
• Caching strategies