Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

Help for owners

My Android app links will not verify and keep opening the browser

Short answer

Android verifies each web address your app declares by requesting a Digital Asset Links file at /.well-known/assetlinks.json on that host. If the file is missing, wrong, or does not match the app, the domain is not verified and links open in the browser. Updated files can take up to seven days to reach all phones on Android 15 and later.

  • Written for business owners
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Does this sound like your situation?

  • The domain shows as not verified on the test phone.
  • Links to my website open the browser and never the app.
  • I changed the file on the server but nothing changed on phones.
  • It verifies for one address but not for www or a subdomain.
  • A release build fails while the debug build worked.

Why does this happen?

  1. The file is not where Android looks

    For each unique host in the app's link declarations, Android requests the Digital Asset Links file at https://hostname/.well-known/assetlinks.json. The www address and the plain address are different hosts, and each needs its own.

  2. One host failing can spoil the rest on older Android

    On Android 11 and lower, the app becomes the default handler only if a matching file is found for all hosts in the manifest. A single forgotten host can switch the whole app off for links.

  3. Verification is not instant

    After installing, Android's own guide says to wait at least 20 seconds for the asynchronous check. For later changes on Android 15 and higher, the system re-verifies in the background, and changes can take up to seven days to reach all devices. On Android 14 and lower, updates are generally picked up only at install or update.

  4. The state is not what you assume

    Android reports each domain as verified, none (not finished yet), legacy failure or an error code. Anything other than verified means verification was not completed, and none can mean the check has not finished.

  5. Another app or a cached file gets in the way

    On a given device, only one app at a time can be associated with a particular domain, so another app can block yours. Android also notes that server-side caches might delay delivery of an updated assetlinks.json, and a firewall, login wall or redirect in front of that path can hide the file.

What can I do about it today?

  1. Open the file address in a browserType your domain followed by /.well-known/assetlinks.json. You should see text, not an error page or a login screen. Note what you see.
  2. List every address your links useWith and without www, and any subdomains. Each one needs checking.
  3. Do not change the file many times in a rowSince updates take time to reach phones, repeated edits make it hard to tell what works.
  4. Keep the app's store release as it isVerification problems rarely need a new app release. Do not unpublish anything.
  5. Give the developer the phone model and Android versionVerification works differently across versions.

When should I bring someone in?

  • The file opens correctly in a browser and links still fail.
  • Your site sits behind a CDN, a firewall or a login layer.
  • You use several build variants or signing keys.

How do I handle it?

  1. Read the verification state on a deviceI use Android's documented commands to reset link state, trigger a re-check and read the result per domain.
  2. Check the file from the outsideI request the file the way Android would, over HTTPS, and look at what the server and any firewall return.
  3. Match app and fileI compare the app's declared hosts, package name and signing certificates against what the file lists, including the store's signing.
  4. Retest and explain the waitI test on versions you support and tell you plainly how long reach to all phones can take.

The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.

What do owners ask about this?

How long until it works for everyone?

Android's guide says on Android 15 and higher changes can take up to seven days to propagate. On Android 14 and lower, updates are typically picked up when the app is installed or updated.

Does the file need a new app release?

Often not. The file lives on your website. A release is needed only if the app's own declaration is wrong.

Can users fix it themselves?

Android lets users associate the app with a domain in the Open by default settings, but you should not rely on customers doing so.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.

For your developer: the technical fixes

Next step

Want this off your desk?

Send me a few lines on where things stand. I reply within 24 hours.