Deep link opens the browser instead of the app

Definition

A deep link opens the browser instead of the app when the operating system has not accepted the app as a verified handler for that URL, or when the tap occurred in a context that never offers the app the chance to handle it.

This is the same visible symptom for roughly two dozen distinct causes across both platforms, which is why it is so often debugged by trying things. It does not need to be. Almost every cause announces itself through some other observable — whether it happens on both platforms, whether it happens from every app, whether it started recently — and three or four such observations narrow two dozen causes down to one or two.

Triage: three questions

Answer these before touching any configuration. Each one cuts the space roughly in half, and together they usually identify the cause outright.

The five underlying causes

1. The association or verification layer is broken. The OS never accepted your app as a handler for the domain. On iOS that means the AASA file was not fetched, or the entitlement is missing; on Android it means App Links verification failed, usually a fingerprint mismatch. This is the cause most of the time, and it is the one that fails from every app, on every device, consistently.

# Android: per-domain verification state. "verified" or nothing else will do.
adb shell pm get-app-links com.example.shop

# iOS, from macOS: association state and the reason for any failure
swcutil show --domain example.com

# Both files, as the platforms fetch them — no redirects followed
curl -sSI --max-redirs 0 https://example.com/.well-known/assetlinks.json
curl -sSI --max-redirs 0 https://example.com/.well-known/apple-app-site-association

2. The URL does not match your path rules. Association is fine and this particular URL is not claimed. On iOS that is the components array, evaluated top to bottom with the first match winning, so an exclude below a broad wildcard is dead code. On Android it is the <data> elements of the intent filter — and an intent filter that declares android:host but no android:pathPrefix claims the whole host, while one with a pathPrefix claims only that subtree. A URL with a query string or a fragment can also fall outside rules that only considered the path.

3. A redirect stands between the tap and your domain. Neither platform resolves redirects before deciding. The tap is evaluated against the URL being navigated to, so a link that points at click.tracker.com and 302s to example.com is a link to the tracker as far as the OS is concerned. Email click tracking, ad network click servers, and most link shorteners insert exactly this hop, which is why the same URL works when pasted into Notes and fails from a campaign.

4. It is a custom URI scheme, not a verified web link. myapp://product/42 is a URI scheme, and modern browsers on both platforms suppress scheme navigation that is not a direct user gesture — with no error, and no fallback if the app is absent. Custom schemes are still useful app-to-app, but a scheme link in an email, an ad, or a web page in 2026 will mostly do nothing. Universal Links and App Links exist because of exactly this.

5. The tap happened inside an in-app browser. Instagram, TikTok, LinkedIn, Facebook, and most chat apps render links in an embedded webview that never hands the URL to the OS. Your configuration is irrelevant inside one — the link cannot reach the app because nothing ever asks the OS to resolve it. This is the single most common cause of "works when I test it, fails for real users", because engineers test from Notes and users tap from social apps. See deep links in in-app browsers.

The app is not installed

Worth stating plainly because it is sometimes the whole answer: a Universal Link or App Link to a device without the app installed opens the browser. That is the design — the URL is a real web URL and the web page is the fallback. Nothing is broken.

What that surfaces is a product question rather than a bug. The user tapped a link meaning to reach a specific thing, and if they install the app at that point, the destination is lost unless you carry it across the install. That is deferred deep linking, and it is a separate mechanism that has to be built rather than configured.