Deep link on iOS not working
Four different mechanisms produce the same symptom. Debugging the wrong one costs a day, so the order of checks matters more than the checks themselves.
6 August 2026 by PAD team
Work out which mechanism you are debugging
| What you tap | What should happen | What breaks it |
|---|---|---|
myapp://path | app opens | scheme not registered, or no app installed |
https://yourdomain.com/path | app opens | universal link not verified |
https://apps.apple.com/... | store opens | in-app browser cannot follow Apple's redirect |
| a tracker link | app or store opens | any of the three above, one hop later |
The last row is why tracker links are so miserable to debug: they inherit every failure mode of the destination and add a redirect on top.
Custom schemes
A scheme like myapp:// only works if the app is installed. If it is not, nothing happens at all, and the browser stays where it was with no error. That is why a scheme should never be the only route.
The scheme also has to be declared in the app's Info.plist under CFBundleURLTypes, and it is case sensitive in practice even though it should not be.
Universal links
These are the ones that fail silently and confusingly. iOS fetches a file from your domain that grants the app permission to handle its URLs, caches the result, and falls back to opening the page in a browser if anything is wrong:
https://yourdomain.com/.well-known/apple-app-site-associationIt must be served over HTTPS with no redirect, no .json extension, and content type application/json. There is no error surface, so a malformed file and an expired certificate look identical from the outside. The full checklist is in the universal links write-up.
Cases iOS refuses on purpose
- A URL typed into Safari's address bar never opens the app
- A link to the same domain as the current page stays in the browser
- Once the visitor taps the breadcrumb in Safari, iOS remembers and stops opening the app
- Inside most in-app browsers, universal links are unreliable by design
The in-app browser layer
If the tap comes from Instagram, Facebook or TikTok, none of the above may even get a chance to run. Those browsers intercept navigation before iOS decides anything, which is a separate problem with a separate fix, covered in the main write-up.
If the last hop is a store link, we handle the escape from in-app browsers and can carry your deep link alongside it.