Why Is My PWA Not Installable?
The eight things that stop the install prompt, how to recognise each one, and the fix.
Check your site first
Chrome only offers to install a site when a short list of conditions is met, and it does not say which one failed. Working through them by hand is slow, because several look fine in the source and still fail in practice.
The quickest route is to enter your address in the PWA validator, which tests every cause on this page against your live site and names the one that applies. The rest of this guide explains each result.
1. The page is not served over HTTPS
Browsers install apps only from secure origins. A page loaded over plain http:// is never installable, whatever its manifest says. The one exception is localhost, which is treated as secure so that you can develop.
Fix: install a TLS certificate, which most hosts provide for free, and redirect every http:// request to https:// with a permanent redirect.
2. The page has no manifest link
The browser finds the manifest through a link tag in the head of the page. If the tag is missing from the page you are on, that page is not installable, even when the manifest file exists and other pages link to it.
Fix: add the tag to every page, in the HTML itself. A tag that is added later by JavaScript is easy to miss in testing and is not seen by tools that read the HTML.
HTML head
<link rel="manifest" href="/manifest.json">3. The manifest does not load, or is not JSON
A manifest link that points to the wrong path is the most common fault in single-page apps. The server cannot find the file, falls back to the index page, and answers with HTML and a 200 status. Everything looks successful in the network panel, but the browser cannot parse HTML as a manifest.
The other form of this fault is invalid JSON: a trailing comma, single quotes or a comment. JSON allows none of them.
Fix: open the manifest address directly in the browser. You should see JSON, not your site. If you see the site, put the file in the public or static folder so it is deployed as a file.
4. name, short_name or start_url is missing
The manifest needs a name or a short_name, which becomes the label under the icon, and a start_url, which is the page the app opens on. The start_url must be on the same origin as the page and inside the manifest scope.
manifest.json
"name": "My PWA App",
"short_name": "App",
"start_url": "/"If you are writing the file from scratch, the manifest generator produces one with every required field and checks it as you type.
5. display is set to browser
The display field says how the installed app opens. Chrome offers installation only when it is standalone, fullscreen, minimal-ui or window-controls-overlay. The value browser means an ordinary tab, so there is nothing to install. A manifest with no display field defaults to browser.
manifest.json
"display": "standalone"6. The 192x192 or 512x512 icon is missing
Chrome asks for two PNG icons in the manifest: 192x192, used on the home screen, and 512x512, used in the install dialog and on the Android splash screen. A manifest that lists only a favicon or a single small icon does not qualify.
manifest.json
"icons": [
{ "src": "/icons/icon-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
{ "src": "/icons/icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" }
]The PWA icon generator creates both sizes, and the maskable versions Android prefers, from one image.
7. An icon is listed but does not work
The manifest can be perfectly valid and still point at icons that fail. The path returns a 404, or returns the index page because of the same fallback described above, or the file is a different size from the one declared: a 256x256 image listed as 512x512, for example.
This is the hardest cause to spot by reading the manifest, because nothing in the JSON is wrong. Each icon has to be downloaded and measured.
Fix: open each icon address in the browser and confirm that it is an image of the stated size. In the icons array, sizes must match the real pixel dimensions of the file.
8. prefer_related_applications is true
This field tells the browser that you would rather people install your native app from a store. When it is true, Chrome promotes that app and does not offer to install the PWA. It is sometimes copied from a template without being noticed.
Fix: remove the field, or set it to false.
Everything passes and there is still no prompt
If every requirement is met, check the circumstances. The app may already be installed, in which case the browser has nothing to offer. Chrome does not offer installation in an incognito window. And Safari on iPhone and iPad never shows a prompt at all: people install from the Share menu with Add to Home Screen, so the absence of a prompt there does not mean anything is wrong.
A service worker is no longer required by Chrome for the install prompt. It is still needed for the app to open offline, which is the first thing people notice after installing.
Frequently Asked Questions
How do I check if my PWA is installable?
Enter the address in the PWA validator on this site. It loads the page, the manifest and every icon, and reports which install requirement fails. In Chrome you can also open DevTools, choose Application and then Manifest, where installability warnings are listed.
Why is there no install button on my iPhone?
Safari on iOS does not show an install prompt for any site. To install a PWA, open the Share menu and choose Add to Home Screen. Add an apple-touch-icon so the home screen shows your icon.
Does a PWA need a service worker to be installable?
Not in current versions of Chrome, which need only a valid manifest served over HTTPS. A service worker is still required for the app to work offline.
My manifest is valid. Why does Chrome still say it is not installable?
A valid manifest can still list icons that fail to load or that are a different size from the one declared. Check that the 192x192 and 512x512 icon addresses return real images of those sizes.