DocsTroubleshooting

Troubleshooting

No Web App Manifest discoverable

Add to the document that is fetched:

<link rel="manifest" href="/manifest.webmanifest" />

The href may be relative. PWARegistry does not guess /manifest.json.

Manifest is invalid

Serve JSON. The root value must be an object, not an array. Check for trailing commas and comments — standard JSON does not allow them.

Display is browser

Set "display": "standalone" (or fullscreen / minimal-ui) in the manifest.

Start URL outside scope

start_url is resolved against the manifest URL, not the page URL. If the manifest lives at https://example.com/app/manifest.json, a start_url of / is https://example.com/, which is outside the default scope https://example.com/app/. Use "start_url": "./" or set an explicit scope.

Icons fail

  • src must resolve over HTTPS and return an image (PNG, SVG, WebP, JPEG, ICO, GIF, AVIF, BMP).
  • At least one general-purpose (any) icon should be 192×192 or larger.
  • A 404 icon is a broken asset, not a missing optional extra.

Service worker not detected

PWARegistry looks for navigator.serviceWorker.register in inline scripts and a small number of same-origin script files. Bundlers that hide the call behind a helper still usually match. A worker that is only registered after a user gesture may not be visible to the static scan — that yields a warning, not a failure.

The site works in Chrome but fails here

Chrome can use additional installability signals (including a browser). PWARegistry’s bar is the documented check list, applied without executing page JavaScript. Align the published manifest with those checks.