# Debug a PWA

> How to use Chrome DevTools' Application panel — Manifest, Service Workers, Cache Storage — to inspect and troubleshoot a PWA while developing it.

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

```js
// 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](/reference/service-worker/debugging/) — more on
  inspecting service workers across browsers
- [The update flow and skipWaiting](/reference/service-worker/update-skipwaiting/)
- [Caching strategies](/reference/service-worker/caching-strategies/)