Why iOS Changes Your PWA URL When Adding to Home Screen (Fix & Causes)

Last updated: 2026/04/23

Have you ever added a web app to your iPhone home screen and noticed that the saved URL is different from the one you opened?

For example, you open /petal/{token}, but the home screen icon points to /petal/@username instead.

The cause is simple: your manifest.json configuration.

The Cause: maskable Icon + start_url

Here’s an example of a problematic manifest:

{
  "name": "Business Card App",
  "short_name": "Petal",
  "display": "standalone",
  "start_url": "/petal/@ojapp",
  "icons": [
    {
      "src": "/icon.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

At first glance, this looks fine. But it can trigger unexpected behavior on iOS:

• iOS treats the page as a PWA
• start_url is prioritized
• The current URL gets overridden

In short, iOS saves the start_url instead of the current page URL.

Why This Happens on iOS

Safari on iOS usually ignores most of the manifest.

However, when certain conditions are met, its behavior changes:

• display: standalone
• A maskable icon is present
• The app looks like a PWA

Under these conditions, start_url may become active.

That’s what caused this issue.

How to Fix It

1. Update the icon purpose

{
  "purpose": "any maskable"
}

This allows Android to use maskable icons, while iOS is more likely to ignore them.

If you use only "maskable", iOS may switch into PWA-like behavior and start using start_url.

2. Remove or change start_url

{
  "start_url": "."
}

The value "." means “use the current URL.”

This prevents iOS from overriding the URL when adding to the home screen.

Key Design Considerations

The URL saved to the home screen is determined by:

• The current address bar URL
• start_url (in certain cases)

iOS behavior is inconsistent and can change without notice.

To avoid issues:

• Do not overwrite URLs unnecessarily
• Avoid hardcoding fixed URLs in manifest

In this case, I had incorrectly set the URL, but it didn’t break anything—until I added "purpose": "maskable".
That’s when iOS started treating it as a PWA and applied start_url, causing the issue. (Yes… that was my mistake.)

Summary

• Using maskable alone can be risky
• start_url may be applied on iOS
• This can override the current URL
• Fix it with "any maskable" and "start_url": "."

PWA support on iOS is still evolving.

If something suddenly stops working, check your manifest first.