Why your deep link doesn't open the app — three causes and how to check each one

The symptom is always the same and always annoying: you tap the link and it opens in the browser. The app is installed, the link is correct, there's no error.
There won't be an error later either — that's the cruel part. A failed domain verification looks exactly like an ordinary website link. Let's go through the three causes, most common first.
First, work out which kind of link you have
Thirty seconds that save an evening.
If your link looks like myapp://something, that's a scheme, and none of the diagnostics below apply. A scheme fails to open the app in one case only: the app isn't installed, or another app grabbed the scheme. And it will never open in a browser — it simply does nothing.
If your link looks like a normal https://yourproject.com/..., that's a universal link — keep reading. The difference between the two is covered in what a deep link is.
Cause 1: the verification file isn't served the way it must be
This is nine cases out of ten.
The phone looks for a file on your domain: on Android /.well-known/assetlinks.json, on iOS /.well-known/apple-app-site-association. Didn't find it, or got something else — it silently decides the link isn't yours.
How to check. Open the file's address in a desktop browser. Look at four things:
- does it come back at all (not a 404, not a login page);
- is it over HTTPS — plain http doesn't count;
- is there a redirect: if the address in the bar changed (a
wwwor a trailing slash appeared), verification already failed — redirects aren't allowed; - do you get JSON, not your site's HTML page. Frameworks often answer an unknown path with a pretty page and status 200 — to the phone that's garbage.
How to fix. Serve the file as a static asset, straight from that path, with type application/json. Make sure your www or trailing-slash redirect rule doesn't touch .well-known. The iOS file must have no .json extension — just apple-app-site-association.
One small detail that breaks everything: check the identifiers inside the file. On Android it's the signing certificate fingerprint (debug and release builds have different ones!), on iOS the team prefix and bundle id.
Cause 2: the check already failed and got cached
You found the mistake from cause 1, fixed the file, reloaded — and the link still goes to the browser. This is where people start "fixing" things that already work.
How to check. Just recall: was the file broken at the moment you installed the app?
On Android domain verification runs at install time. The app was installed while the file was wrong, so "not verified" got recorded, and editing the file doesn't undo that by itself.
On iOS the file isn't fetched from your server directly but through Apple's CDN — a fresh version doesn't propagate instantly.
How to fix. Reinstall the app — the fastest way to make Android re-verify the domain. On iOS, reinstall plus a little patience. Also check your phone's settings under opening links by default: you can see there whether your link is recognised as belonging to the app. If the system offers you a manual choice, automatic verification didn't pass.
Cause 3: the link was opened from the wrong place
The link is fine, the file is correct, and Telegram still opens the web version.
That's by design. Built-in browsers in messengers and social apps often open the address inside themselves and never hand it to the system — so the app never gets a chance to claim it.
How to check. Send yourself the same link in notes or email and tap it there. If the app opens, the link is fine and the problem is where you tapped it.
How to fix. Fully, you can't — it's someone else's behaviour. What actually helps:
- make the web page at that address a decent one, with an "Open in app" button;
- don't run the link through trackers or shorteners — a redirect on the way also breaks the match;
- in emails and notifications, point at your own domain directly, not through an intermediary service.
The order to work through
Short version if you're fixing this right now:
- Open the verification file in a browser — redirects and HTML are ruled out immediately.
- Compare the signing fingerprint and bundle id in the file with the build on the phone.
- Reinstall the app.
- Test the link from notes, not from a messenger.
If it works after step four, you found cause 3 and there's nothing left to fix.
Why is there no error at all?
Because to the system this isn't an error. It asked, got no valid answer, and did the safe thing: opened a normal web page. The silence is deliberate — otherwise any website could show users someone else's system errors.
It works in the simulator but not on a phone — why?
Usually the build signature: the file lists one build's fingerprint while the device has another. Test deep links on the same build you ship to people — debugging on a different version is useless here.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





