Debug a PWA
Published Updated
The Chrome DevTools Application panel lets you inspect a PWA’s parsed manifest and exact installability failures, force a service worker update, simulate offline, and inspect or clear Cache Storage entries. Firefox and Safari have different developer-tools interfaces.
You need Chrome with DevTools open on the page under test. Open the panel with
Command+Shift+P (macOS) or Control+Shift+P (Windows, Linux, ChromeOS), type
application, and choose Show Application; the sidebar lists Manifest,
Service workers, and Storage under “Application”, and Cache storage under
“Storage”.
Read the parsed manifest and the Installability verdict
Section titled “Read the parsed manifest and the Installability verdict”Select Manifest. The pane shows the manifest URL under App Manifest, then the Identity, Presentation, and Icons sections with every declared icon rendered. The checkbox Show only the minimum safe area for maskable icons crops each icon to the area a masked launcher keeps, which is the quickest way to catch artwork that touches the edge. Under Protocol Handlers, the Test protocol button opens a URL with a declared scheme so you can confirm the registration. An Installability section appears only when Chrome finds a problem, and each line is one of a fixed set of strings from the DevTools front end. The ones that come up most while developing are:
Page has no manifest <link> URLManifest couldn't be fetched, is empty, or couldn't be parsedManifest doesn't contain a 'name' or 'short_name' fieldManifest 'start_url' isn't validManifest 'display' property must be one of 'standalone', 'fullscreen', or 'minimal-ui'Couldn't download a required icon from the manifestPage isn't served from a secure origin
Each names the manifest member or server condition to fix; the section disappears once the page meets the criteria.
Control the service worker from the Service workers pane
Section titled “Control the service worker from the Service workers pane”Select Service workers. For the registration in scope the pane prints Source (the
script URL and when it was received), Status (#N activated and is running, with
stop and start links), and Clients. Three checkboxes change how Chrome treats
the worker while the box is ticked:
| Control | Effect |
|---|---|
| Offline | Puts the page into the same offline mode as the Network panel |
| Update on reload | Forces the service worker to update on every page load |
| Bypass for network | Sends every request straight to the network, ignoring the fetch handler |
The Update link runs one update check; Unregister removes the registration; Push
and Sync dispatch a push event (default payload Test push message from DevTools) and a
sync event to the worker. The Update Cycle table lists the install, wait, and activate
timestamps of each version, which tells you which phase a worker that “will not update” is
stuck in. The page script should still guard registration so a browser without the API loads
the page normally:
if ('serviceWorker' in navigator) { navigator.serviceWorker.register('/sw.js').then((registration) => { console.log('scope', registration.scope); });} else { console.info('Service workers unavailable; running without offline support');}A worker with waiting set in the table is installed but not controlling the page because
an older version still owns an open client; close every tab of the origin or tick Update
on reload to let it activate.
Inspect and clear Cache storage
Section titled “Inspect and clear Cache storage”Under Storage, expand Cache storage to see one entry per caches.open() name. Select
one to list the cached requests with their response status, content type, and size; an entry
marked opaque is a cross-origin response fetched without CORS; Chrome’s guide notes that opaque
entries affect how their size counts against the origin’s quota. Clear storage (top of
the Application section) unregisters service workers and deletes caches, IndexedDB, and local
storage in one click, which resets the origin between test runs.
Reproduce an offline launch
Section titled “Reproduce an offline launch”Tick Offline in the Service workers pane, then reload. A page with a working fetch handler renders from cache; a page without one shows Chrome’s offline error page. Since Chrome 108 on Android and Chrome 112 on desktop a site installs from the browser menu without a fetch handler, and Chrome supplies a default offline page for installed apps that lack one, so an offline failure in this test no longer blocks installation but still means your users see Chrome’s page rather than yours. Untick Offline before testing anything else; the setting persists for the DevTools session.
See also
Section titled “See also”- Debugging service workers
- The update flow and skipWaiting
- Cache Storage
- Debug Progressive Web Apps (developer.chrome.com)
- Application panel overview (developer.chrome.com)