PWA TROUBLESHOOTING
Common PWA installation failures and how to fix them
A progressive web app needs several pieces to work together. One missing icon or an unreachable service worker can stop an otherwise good site from feeling installable.
Install criteria vary by browser and platform and can change. Treat automated checks as readiness guidance, then confirm installation on the browsers you support.
1. The site is not fully secure
Production PWAs should be served over HTTPS. Check that the page, manifest, service worker, icons and imported scripts are all available securely. Mixed HTTP assets can break registration or weaken the installed experience.
2. The manifest is missing or unreadable
Link the manifest from the page with <link rel="manifest" href="/site.webmanifest">. Open the manifest URL directly and confirm it returns valid JSON with an appropriate content type—not a login page, redirect loop or HTML error.
3. The app has no usable identity
Provide name or short_name, a valid start_url and an app-like display value such as standalone. Keep the start URL inside the manifest's effective scope.
4. Icon declarations are incomplete
Include exact 192×192 and 512×512 PNG icon declarations. Make sure each src loads, the declared sizes match the real file and the artwork remains recognisable when platforms crop it. A separate maskable icon is useful.
5. No service worker controls the page
Register the service worker from a secure page, ensure its path gives it the scope you expect and handle install/activate failures in browser developer tools. A file that exists but never registers does not help.
6. A related native app is preferred
If prefer_related_applications is true, some browsers may direct people toward a native app instead. Leave it false or remove it when the web app itself should be installable.
7. The browser does not show a prompt
A missing automatic prompt does not always mean the PWA is broken. Browsers use engagement rules and platform-specific UI. Look for an install action in the address bar or browser menu and test on a clean profile.
8. Old cached files hide your fix
Service workers are intentionally persistent. Update cache names and service-worker logic carefully, close old tabs, unregister during development when necessary and retest in a clean browser profile.
Core PWA readiness list
Check the core PWA requirements
ViewpointPro reports what is present and highlights the missing pieces separately from general website health.
