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

Fix Progressive Web App (PWA) installation errors including install button not appearing, service worker registration failures, and manifest.json issues. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: 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. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: 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. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Check PWA criteria: Chrome DevTools > Application > Manifest and Service Workers panels. Run Lighthouse PWA audit: Chrome DevTools > Lighthouse > check Progressive Web App. Fix manifest: ensure all required fields are present and icons are accessible. Register service worker: navigator.serviceWorker.register('/sw.js') from the page's JavaScript. Check HTTPS: PWAs require a secure context — use a valid SSL certificate. For testing: chrome://flags > enable 'Bypass PWA install criteria' (development only). If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our Browser Errors collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.