◆Error Codes Wiki

Progressive Web App Installation Errors — PWA Install and Service Worker Failures

Warningweb development

Overview

Fix Progressive Web App (PWA) installation errors including install button not appearing, service worker registration failures, and manifest.json issues.

Key Details

  • PWAs require: HTTPS, a valid web app manifest (manifest.json), and a registered service worker
  • The install prompt appears only when Chrome/Edge detect the PWA meets all installability criteria
  • Service worker registration can fail due to scope mismatch, HTTPS issues, or script errors
  • The manifest must include: name, short_name, start_url, display, and at least one icon (192x192 and 512x512)
  • PWAs can work offline if the service worker correctly caches assets and handles fetch events

Common Causes

  • Missing or invalid manifest.json fields preventing installability
  • Site not served over HTTPS (required for service workers and PWA installation)
  • Service worker registration failing due to JavaScript errors in the worker script
  • Service worker scope not covering the start_url defined in the manifest
  • Browser already has the PWA installed — no duplicate install prompt shown

Steps

  1. 1Check PWA criteria: Chrome DevTools > Application > Manifest and Service Workers panels
  2. 2Run Lighthouse PWA audit: Chrome DevTools > Lighthouse > check Progressive Web App
  3. 3Fix manifest: ensure all required fields are present and icons are accessible
  4. 4Register service worker: navigator.serviceWorker.register('/sw.js') from the page's JavaScript
  5. 5Check HTTPS: PWAs require a secure context — use a valid SSL certificate
  6. 6For testing: chrome://flags > enable 'Bypass PWA install criteria' (development only)

Tags

pwaprogressive-web-appservice-workermanifestinstallable

Related Items

browser-service-worker-errorbrowser-service-worker-errors

More in Web Development

browser-cors-error-explainedBrowser CORS Error Explained — Cross-Origin Request Blocked
Warning
browser-websocket-errorsBrowser WebSocket Errors — Connection Failed, Closed & Protocol Errors
Warning
browser-indexeddb-errorsBrowser IndexedDB Errors — Quota Exceeded, Blocked & Corruption
Warning
browser-localstorage-quota-exceededBrowser localStorage Quota Exceeded — Storage Limit & Alternatives
Warning
browser-service-worker-errorsBrowser Service Worker Errors — Registration, Cache & Update Failures
Warning
browser-webgl-context-lostBrowser WebGL Context Lost — GPU Rendering Failure in Browser
Warning

Frequently Asked Questions

Chrome only shows the install prompt when all criteria are met: HTTPS, valid manifest with required fields, registered service worker with a fetch handler, and user engagement (interaction with the page).