Deep Link Not Working: Diagnosis Checklist

Deep links are supposed to open the app at the right screen. When they do not, users are dumped on the home screen, left on a 404, or the app opens but lands somewhere wrong. Diagnosis requires checki

Deep links are supposed to open the app at the right screen. When they do not, users are dumped on the home screen, left on a 404, or the app opens but lands somewhere wrong. Diagnosis requires checking intent filters, deferred link services, navigation stacks, and sometimes provider misconfiguration. This guide is the checklist.

Symptoms

• Link opens browser instead of app
• Link opens app but lands on home screen, not deep screen
• Link works from some contexts (SMS) but not others (Instagram)
• Cold start with deep link loses the link
• Link requires login, lands on login but does not return to deep destination post-login
• Link works in debug, not release

Causes

1. Intent filter misconfigured (Android)

AndroidManifest.xml intent filter does not match the URL pattern.

Fix:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="myapp.com" />
</intent-filter>

2. Universal Link association file (iOS) incorrect

.well-known/apple-app-site-association on your domain either missing, malformed, served with wrong content-type, or does not list your app.

Fix: Serve at https://myapp.com/.well-known/apple-app-site-association with Content-Type: application/json. Verify with swcutil dl -d myapp.com.

3. App Links verification failed (Android)

You set android:autoVerify="true" but the domain does not have the digital asset links file.

Fix: Serve https://myapp.com/.well-known/assetlinks.json with correct package name and SHA256 fingerprint.

4. Cold-start intent lost

Splash activity consumes intent, main activity never sees it.

Fix: Splash reads intent, passes forward (via Bundle or navigator).

5. Deferred deep links (install + deep link) not configured

User taps link on a device without app installed. Goes to Play / App Store, installs, opens app. App should jump to deep destination. Default behavior: opens home.

Fix: Firebase Dynamic Links (deprecating), Branch, AppsFlyer, or custom install-referrer implementation.

6. Navigation stack conflict

App already open. Deep link arrives. Current state has incomplete flow on stack. Deep link navigates on top, user can't back out.

Fix: Clear appropriate stack levels. Use clearTop / singleTask strategically.

7. Auth required, post-auth return broken

Deep link requires login. User not logged in. Login flow redirects user. Post-login, user lands on home, not original destination.

Fix: Store deep link intent. After successful login, replay.

8. Instagram / Facebook in-app browser

Links inside Facebook / Instagram open in the app's internal browser. Custom schemes may not trigger native app.

Fix: Universal Links / App Links. These work from in-app browsers.

9. Custom scheme no longer supported

You ship only myapp:// scheme. In 2026, many contexts strip custom schemes.

Fix: Implement https:// scheme as primary; keep custom for backward compat.

10. Query parameters not parsed

Link is https://myapp.com/product/123?ref=campaign. App parses path but drops query.

Fix: Parse full URI including query and fragment.

11. URL encoding issues

Spaces, unicode in URL not properly encoded / decoded.

Fix: Strict URL encoding at generation; decode correctly in app.

12. Production build release not verified with store

App Links verification requires signing with the same certificate declared in assetlinks.json. Debug-signed build has a different SHA, verification fails.

Fix: Update assetlinks.json with release signing SHA.

Diagnosis

Android

# Verify intent filter
adb shell pm get-app-links com.example
# Should show "verified" for your domain

# Manually fire intent
adb shell am start -a android.intent.action.VIEW -d "https://myapp.com/product/123"

iOS

Use Safari URL bar. If app does not open, Universal Link association is broken.

DevTools

xcrun simctl openurl booted "https://myapp.com/product/123"

Logs

Add logging at every step of deep-link handling: received, parsed, action taken. Ship debug builds with verbose link logs.

Fix patterns

• Single handler for all deep links. One place processes incoming URIs; routes to destination.
• Graceful fallback. Unknown URI → home screen. Not a crash.
• Test matrix. Source contexts: Messages, Email, Safari, Chrome, Instagram, Slack, WhatsApp. States: installed fg, installed bg, installed killed, not installed.
• Analytics. Log deep-link-received events; compare to actual app opens.

How SUSA tests deep links

SUSA launches apps with deep-link intents and verifies the landing screen. Flow verdict: "deep-link-success" or "deep-link-to-wrong-screen" or "deep-link-crash."

susatest-agent test myapp.apk --deep-link "myapp://product/123"
susatest-agent test myapp.apk --deep-link "https://myapp.com/orders/456"

adversarial persona tries malformed deep links (injection, path traversal, very long).

Prevention

• Test every supported deep link source in CI (at least: Safari, Messages on iOS; Chrome, Messages on Android)
• Monitor deep-link error rate in production
• Dedicated deep-link regression suite

Deep links are fragile. Every release potentially breaks a filter, breaks a scheme, breaks association. Constant vigilance.