Your PWA does not load at all

Q: The icon launches and closes immediately. What is that?

Almost always `start_url` returning a redirect the app cannot follow, or a crash in the first script. Open `start_url` cold in a private window; if it redirects to an external domain outside `scope`, the standalone window has nowhere valid to go and closes.

Q: It works on desktop but not on the phone. Where do I look?

At the platform, not the app. Start with [iOS-specific behaviour](/blog/pwa-not-working-on-ios) if it is an iPhone, or [Android's](/blog/pwa-not-working-on-android) otherwise — most cross-device reports resolve to one of those rather than to your code.

Short answer

First separate two symptoms, because they have nothing in common. If the window opens and stays white, the service worker answered with nothing — that is a caching problem. If the app does not open at all, or the icon launches and closes, the entry point itself is unreachable: start_url returns an error, redirects somewhere the app cannot render, or falls outside scope. Open start_url directly in a private window; if it does not render there, it will not render in the installed app either.

Blank is not the same as dead

A white window means the app launched and something answered the request with nothing. A window that never appears, or closes immediately, means the launch itself failed. Treating them as one problem is why this takes people hours.

For the white case, go straight to the four caching causes. For the launch case, keep reading.

Mentioned here: ✏️ Excalidraw, 🔐 CryptPad, 🗜️ Squoosh

start_url is the whole story

The installed app launches start_url and nothing else. If that path 404s, if it redirects to a login the app cannot render without a session, or if it sits outside scope, the launch fails and no error surfaces anywhere the user can see.

Test it the way the app does: open start_url in a private window, cold, with no session. That reproduces the installed launch more faithfully than any devtools panel.

The manifest that answers nothing

A page can declare a manifest that no longer exists. The site works, the browser silently declines to install, and nobody notices because ordinary browsing never touches the file.

We scanned every app in this directory on 12 August 2026: of 386, three declare a manifest URL that returns nothing at all. It is rare — but when it is your app, no browser anywhere will offer to install it, and there is no symptom until someone tells you.

Relative paths that resolve one level too high

A subtle one worth knowing, because we hit it ourselves while measuring. A manifest declared as manifest.json resolves against the page URL. If your host redirects /app to /app/ and something reads the pre-redirect URL, the path resolves to /manifest.json at the domain root instead of inside your folder.

Browsers follow the redirect before resolving and never get this wrong. Tools do. If a checker tells you your manifest is missing while the browser installs your app happily, believe the browser and check the tool.

Frequently asked

The icon launches and closes immediately. What is that?

Almost always start_url returning a redirect the app cannot follow, or a crash in the first script. Open start_url cold in a private window; if it redirects to an external domain outside scope, the standalone window has nowhere valid to go and closes.

It works on desktop but not on the phone. Where do I look?

At the platform, not the app. Start with iOS-specific behaviour if it is an iPhone, or Android's otherwise — most cross-device reports resolve to one of those rather than to your code.