DEV Community

Rasika Dangamuwa
Rasika Dangamuwa

Posted on

Why Your PWA Isn't Installable: The manifest.json Pitfalls That Silent-Fail in Production

#webdev #javascript #pwa #frontend

Building a Progressive Web App (PWA) seems straightforward on paper: write your web application, register a Service Worker, serve over HTTPS, and drop a manifest.json file into your root directory. Yet developers frequently discover that Chrome, Safari, or Edge refuses to trigger the install prompt, displays broken splash screens, or fails Lighthouse audits without clear error messages.

The culprit is almost always subtle misconfigurations inside manifest.json. Modern web browser engines strictly validate web application manifests before granting installation privileges or custom display frames. Here is a breakdown of why PWA manifests silently fail in production, how browsers process manifest metadata, and how to structure your manifest properly.

1. The Icon Matrix and Maskable Icons

The single most common reason Chromium-based browsers refuse to offer an install prompt is an incomplete icons array. Browsers require specific pixel dimensions and icon formats to render home screen icons, app switchers, and splash screens across high-DPI devices.

At a minimum, your manifest must include 192x192 and 512x512 PNG images. However, Android OS uses maskable icons (adaptive icons with safe zones) to prevent arbitrary cropping. If you provide standard transparent PNGs without specifying icon purpose, Android will wrap your icon in an unsightly white circle or square.

{
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

If your server responds with an incorrect Content-Type header for icon assets (e.g., serving PNGs as text/plain) or returns a 404 due to relative path resolution issues, the browser silently invalidates the entire install candidate.

2. Scope vs. Start URL Mismatches

The start_url property tells the device where to launch the application when tapped from the home screen, while scope defines the URL navigation boundary for the standalone window.

A classic mistake occurs when start_url points outside the defined scope:

{
  "scope": "/app/",
  "start_url": "/index.html"
}
Enter fullscreen mode Exit fullscreen mode

Because /index.html falls outside /app/, Chromium treats the manifest as invalid for PWA installation. Always ensure start_url is relative to or contained within scope. Using query parameters like "start_url": "/?utm_source=pwa" is standard practice for analytics tracking, provided the base path matches the scope.

If you want to avoid syntax typos or scope path errors while drafting your manifest, you can quickly generate a fully spec-compliant JSON file using the free PWA Manifest Generator on Nutilz, which formats icons, theme colors, and display scopes in your browser.

3. Display Modes and Theme Color Bleed

The display field determines how much browser UI is hidden when your application launches:

  • standalone: Hides standard browser navigation bars, making the app feel native.
  • minimal-ui: Keeps basic back/refresh controls (ideal for multi-page web apps).
  • fullscreen: Takes over the entire display (common for games).

Pairing "display": "standalone" with theme_color and background_color controls the system status bar and initial splash screen background:

{
  "name": "DevTools Suite",
  "short_name": "DevTools",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#0f172a",
  "theme_color": "#3b82f6"
}
Enter fullscreen mode Exit fullscreen mode

On iOS Safari, manifest.json display modes were historically ignored in favor of proprietary <meta name="apple-mobile-web-app-capable" content="yes"> tags. While modern iOS versions parse manifest.json, fallback meta tags are still essential to ensure safe-area insets (env(safe-area-inset-top)) render correctly without clipping status bar text.

4. MIME Type and CORS Requirements

Even a perfectly formatted manifest file will fail if your web server mis configures HTTP headers. Web Application Manifests should be served with the header:

Content-Type: application/manifest+json
Enter fullscreen mode Exit fullscreen mode

While browsers often accept application/json, serving manifests as text/html (a common issue in single-page apps with catch-all routing) will fail silently. Furthermore, if your manifest or icon assets are hosted on a CDN or secondary origin, cross-origin requests must include CORS headers (Access-Control-Allow-Origin: *), and your HTML link tag must include crossorigin="use-credentials" or crossorigin="anonymous".

Debugging Your Manifest

Before deploying to production, open Chrome DevTools, navigate to the Application tab, and select Manifest. Chrome will display real-time validation errors, icon previews, and test install triggers.

Creating a solid Web App Manifest requires checking path scopes, pixel dimensions, display modes, and server headers. For rapid generation and testing without manual JSON syntax errors, try the Nutilz PWA Manifest Generator to produce clean manifest files for your next web project.

Top comments (0)