Universal Links Open the App Store? 5 Fixes

Your installed users tap a campaign link and land on the App Store page for an app they already have. A universal link does this when iOS does not treat the tap as a valid universal link: the associated domain or AASA file does not match the link's domain, a redirect sits in front of the link, the app never handles the URL, the user once chose the browser, or the tap came from an in-app browser or a same-domain page.

Check the five causes below in order. Often the first three explain it, and the first step of the flow below takes under a minute.

Why does my universal link open the App Store instead of the app?

A universal link is a standard https link that iOS opens in the associated app instead of the browser, when the domain's apple-app-site-association (AASA) file and the app's Associated Domains entitlement match.
If iOS does not make that match, the link opens in the browser. A tracked link is built to fall back to the store in that situation on mobile, so the store page is the symptom, not the bug. Two exceptions: a custom iOS or Android redirect URL set on the campaign takes priority over the store, and desktop visitors go to the website first.
The job is to find out why iOS did not hand the tap to the app.

The quick diagnostic flow

Run these in order and stop at the first failure.

Test from Notes. Paste the link into the Notes app and long-press it. Apple's guidance is that if universal links are configured correctly, the options to open in your app and in the browser both appear. Typing the URL into Safari's address bar never opens the app, because that is direct navigation within the browser.
Check the AASA file. It must load from /.well-known/apple-app-site-association on the exact link domain, with the right app ID and paths. Paste the domain into the free AASA validator.
Check the entitlement. The app needs an applinks: entry for every domain you use in links.
Check for redirects. Anything between the tap and the AASA domain counts.
Check the context. Where was the link tapped, and has this device ever chosen "open in browser" for this domain?

Cause 1: the AASA file or entitlement does not match the link domain

Apple's debugging guide calls out a domain in applinks: with no AASA file at the matching location as a common problem.
A wildcard entry (applinks:*.example.com) covers the root domain and wildcard subdomains but not a specific subdomain. Each specific subdomain needs its own AASA file.
A port number in the domain (applinks:example.com:8080) will not open the app.
A 403 or 404 on the AASA path usually means a firewall, bot rule or user-agent block. Apple says the file must be reachable from all IP addresses and that your server should accept all user agents.
Avoid mixing the newer components format with the legacy paths format in one file.
Worked yesterday, broken today? Per Apple, devices download the file through Apple's CDN when the app is installed and check for updates about once a week, with no direct CDN invalidation. Editing the file does not instantly change already-installed apps.

For the file layout and hosting steps, see our universal links and App Links setup guide and the deep linking setup docs.

Cause 2: a redirect or tracker sits in front of the link

Apple says the AASA file must be served with a valid certificate and no redirects. A 301 or 302 on the file itself is unsupported.
The same logic applies to the link: if the tapped URL is not itself on your associated domain and only redirects to it, the user is routed through the browser to the app rather than straight in.
Common culprits are link shorteners, email click-wrappers and JavaScript redirects.
In one support case, a link shortener placed in front of Linkrunner links made iOS installs read as organic.
Fix: put the link on your associated domain from the first hop. See link redirection and subdomain setup.

Cause 3: the app never handles the link

Across more than 10 customer groups in early-stage deep link cases, a frequent failure was the app receiving the link but never passing the URL to the SDK's deep link handler on cold start, on warm start, or for links on a second domain.
Fix: call the handler after SDK initialisation on both starts and for every link domain.
For people who do not have the app yet, the route is a deferred deep link, set up through the deferred deep linking docs.

Causes 4 and 5: user choices and in-app browsers

Cause 4, the long-press choice. Apple says the option a user picks when long-pressing a universal link sets the default for that domain on that device. If someone chose the browser once, later taps follow it. Long-press again and pick the app option to reverse it.
Cause 5a, a same-domain tap. Per Apple, if a link has the same domain as the previous navigation in the browser, the browser expects the user to keep browsing. A login button on example.com that links to another example.com path will not open the app. Apple's suggested route is a different subdomain with its own entitlement entry and AASA file.
Cause 5b, in-app browsers. Apple says it is up to third-party browsers to enable universal links, and many in-app browsers do not hand links off. See why links break in in-app browsers and the social media intermediary page.

FAQ

Why does the link work from Notes but not from Safari's address bar? Typing a URL into the address bar is direct navigation within the browser, so iOS never hands it to the app. Test with a tap from Notes or Messages instead.

Does the same fix apply on Android? No. Android uses assetlinks.json and a different verification process. See Android App Links not working? 6 fixes.

How do I test before a campaign goes live? Run the deep link QA checklist on a device with the app installed and a device without it.

Next step

If none of the five explains it, the longer iOS failure-mode guide walks the remaining cases. Linkrunner is a mobile and web attribution platform, and its link setup uses the same AASA and entitlement checks described here. Request a demo from Linkrunner and run this flow against your current links first.