Deep link on iOS not working
Identify the link type before debugging. Custom schemes, universal links and browser redirects depend on different configuration.
19 October 2026 ยท 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.
Create a GoToApp link with your destinations, then test it on the devices and channels you plan to use. Free includes up to three projects.