Why Mobile App Deep Links Fail—and How to Fix the Fallback

A mobile app deep link can fail at several points: the operating system may not associate the domain with the app, the browser may handle the tap itself, or the app may launch without routing to the intended screen. This guide shows how to narrow down the cause and what fallback behavior to expect on iOS and Android.

Key Takeaways

• Custom URL schemes, iOS Universal Links, and Android App Links have different association and fallback behavior.
• For website links, use HTTPS Universal Links and App Links where possible; a custom scheme alone does not provide a dependable web fallback.
• Check the exact URL, domain association file, app configuration, OS handling, and in-app routing—in that order.
• Test both installed and uninstalled states, and repeat tests in the browsers and messaging or email apps your users actually use.
• A successful app launch is not proof that the app opened the correct destination.

Know which kind of link you are testing

A custom URL scheme looks like myapp://product/42. The app registers the scheme and handles matching URLs. It does not establish a verified relationship between the app and a website. If the app is missing, behavior varies by operating system and calling app; there is no built-in guarantee that the user will reach a web page instead.

An iOS Universal Link is an HTTPS URL, such as https://example.com/product/42, associated with an app through an Associated Domains entitlement and an Apple App Site Association (AASA) file on the domain. When the association applies and the user’s context allows it, iOS can open the app. When the app is not installed, the HTTPS URL can open as a normal website.

An Android App Link is an HTTPS URL associated with an Android app using an intent filter and a Digital Asset Links file, assetlinks.json. A verified link can open the app; if the app is absent, the web URL remains available to a browser. On Android 12 and later, unverified web links generally open in the browser rather than automatically opening the app.

These are not interchangeable behaviors. If the URL begins with myapp://, checking an AASA or assetlinks.json file will not fix it. Conversely, a valid HTTPS association does not guarantee that every app, browser, or user preference will open the app.

Troubleshoot in a consistent order

1. Confirm the exact URL and expected destination

Copy the URL that actually failed—not just the URL you intended to send. Check:

• Scheme and host: is it the expected https:// domain, or a custom scheme?
• Path and capitalization: does the app’s route match the path in the link?
• Query parameters and encoding: are values present, encoded correctly, and read by the app?
• Redirects: does a tracking link or shortener send the user through a different host before reaching the destination?

Compare the received URL with the app’s registered paths and routing code. A link can open the app successfully but still show its home screen if the app does not handle the incoming path, query, or cold-start event.

2. Check the domain association files

For iOS Universal Links, check the AASA file at:

https://example.com/.well-known/apple-app-site-association

The file must be valid JSON, served over HTTPS, and match the app identifier and paths you intend to support. Check the app’s Associated Domains entitlement for the corresponding applinks:example.com entry. Each host or subdomain used in links needs the appropriate association; an association for example.com does not automatically cover www.example.com.

For Android App Links, check:

https://example.com/.well-known/assetlinks.json

Confirm that the file identifies the correct Android package and signing certificate fingerprint. The app’s HTTPS intent filter must match the intended host and paths and be configured for verification. A debug signing certificate and a release signing certificate have different fingerprints, so a configuration that works in a debug build may fail for a store-signed build.

In both cases, inspect the response from the exact hostname in the URL. Look for a missing file, invalid JSON, an unexpected redirect, the wrong app identifier or certificate, and a path rule that excludes the link. If you recently changed an association, allow for platform caching and verify again on a device; a file update may not be reflected immediately.

3. Verify app configuration and OS state

On iOS, confirm that the installed build contains the Associated Domains entitlement and that its AASA association covers the link’s host and path. Try a direct HTTPS link in Safari and in another app. iOS may keep a same-domain link in Safari when the user is already browsing that site, and the user’s prior choice can affect link handling. That behavior is not proof that the association file is broken.

On Android, verify the installed package, intent-filter host and path, autoVerify configuration, and signing certificate. On a connected test device, Android’s package manager can show link-verification state:

adb shell pm get-app-links com.example.app

To request verification again on supported Android versions, use:

adb shell pm verify-app-links --re-verify com.example.app

Replace the package name with the one installed on the device. Check the command output and device settings rather than assuming a successful build means the domain was verified. Settings labels and verification behavior vary by Android version and device manufacturer.

4. Test the app’s URL handling

Test both a warm app (already running) and a cold app (not running). Confirm that the app receives the full URL and routes to the intended screen in each case. Also test what happens when the user is signed out, the content no longer exists, or a required query parameter is missing. Provide a useful in-app destination or error state instead of silently dropping the link.

5. Check the opening context

A link tapped in Safari or Chrome may behave differently from the same link tapped in an email client, messaging app, social app, or embedded webview. Some in-app browsers keep navigation inside their own webview, show an “open in browser” control, or handle custom schemes differently. This is controlled by the opening app and operating system, so no single fallback technique works identically everywhere.

For a useful test matrix, try the same HTTPS URL in:

A fresh install does not automatically mean the original link will be replayed after installation. If that experience is required, treat deferred deep linking as a separate feature and test it with the services and platform flows you use.

What fallback should users see?

App absent: With a well-configured HTTPS Universal Link or App Link, the URL can still open the website. Make that page useful on mobile and give users a clear option to continue on the web or install the app. A custom scheme by itself has no dependable website fallback; use a real HTTPS destination as the primary link.

Opened in an in-app browser: The link may stay in the embedded browser even if the app and domain association are configured correctly. Provide a visible way to open the page in the device’s browser, and make the web page work without requiring an app launch. Do not rely on a timed JavaScript redirect as the only fallback: browser restrictions and app-switch behavior make that approach unreliable.

Domain verification fails: The OS may treat an HTTPS link as an ordinary web link instead of opening the app. The site should still serve a sensible page. Fix the association and app configuration, then retest; do not assume a custom-scheme redirect will repair a failed domain association.

Common Mistakes

• Testing only one link-opening app. Email clients, messaging apps, and browsers can handle the same URL differently.
• Checking the wrong host. example.com and www.example.com are distinct hosts for association purposes.
• Using the wrong signing fingerprint. The certificate used for a locally installed build may differ from the certificate used for a distributed app.
• Assuming a launch means routing worked. Verify the actual screen and the cold-start and warm-start handling.
• Expecting installation to resume the original link. App installation and deferred deep linking are separate behaviors.
• Treating a URL parser or file check as full verification. It cannot confirm OS state, user preferences, the opening app’s behavior, or the app’s runtime routing.

Best Practices

• Prefer HTTPS Universal Links and Android App Links for links that should work both with and without the app.
• Keep domain association files valid, publicly reachable over HTTPS, and aligned with the app’s actual identifiers, signing configuration, hosts, and supported paths.
• Keep the website fallback useful, fast, and mobile-friendly; do not make app installation the only route to the content.
• Test real signed builds on real devices, including fresh installs and upgrades, rather than relying only on simulator behavior.
• Log link receipt and route-selection outcomes without collecting unnecessary personal data. This helps distinguish OS association failures from app-routing failures.
• Recheck link behavior after changing domains, signing keys, entitlements, intent filters, or supported paths.

Conclusion

When a mobile app deep link is not working, isolate the failure: inspect the exact URL, validate the platform association, check OS and opening-app behavior, and confirm the app routes the incoming URL correctly. Reliable HTTPS fallbacks and a repeatable device test matrix make the problem easier to diagnose—and the link more useful when the app cannot open.

References

• Apple: Supporting Associated Domains
• Apple: Allowing Apps and Websites to Link to Your Content
• Android: About Android App Links
• Android: Verify Android App Links
• Android: Create Deep Links