Diagnosing Deep Link Failures in React Navigation v6

Recognizable condition

When you tap a link like myapp://settings (or click a universal link) the app opens but stays on the initial screen instead of navigating to the Settings screen.

Cause and diagnostic table

Possible cause	What you observe
Missing or incorrect linking configuration in NavigationContainer	Link is ignored; console may show warning “Could not resolve link”.
Target screen not registered in the navigator	Link falls back to the first route; no warning about missing screen.
URI scheme mismatch between link and native project config	Link does not launch the app at all (or opens a browser fallback).
NavigationContainer unmounted when link arrives	App opens but link event is lost; you see the initial screen and no navigation.

Ordered checks

1. Verify linking prop

   Check that the linking object passed to <NavigationContainer> defines the correct prefixes and a config that maps each path to a screen name.

   import { createLinking } from '@react-navigation/native';
   
   const linking = {
     prefixes: ['myapp://'],
     config: {
       screens: {
         Settings: 'settings',
         Profile: 'profile/:id',
       },
     },
   };
   
   function App() {
     return (
       
         {/* navigators */}
       
     );
   }
   
   If the prefixes do not include the scheme used in the incoming link (e.g., myapp://), the linker will ignore it.
   

2. Confirm screen registration

   Ensure every screen referenced in linking.config.screens is actually present in the navigator’s route list.

   Example: a stack navigator must have a Screen name="Settings" component={SettingsScreen} /> entry.

3. Check native URI scheme configuration

   For Android, open android/app/src/main/AndroidManifest.xml and verify an intent‑filter with the same scheme and host:

   <intent-filter>
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
     <category android:name="android.intent.category.BROWSABLE" />
     <data android:scheme="myapp" />
   </intent-filter>
   
   For iOS, open Info.plist and confirm a URL Types entry with URL identifier and URL Schemes containing myapp.
   

4. Ensure NavigationContainer is mounted when the link is processed

   Avoid rendering the container conditionally before the app finishes launching. A common pattern is to wrap the whole app in NavigationContainer unconditionally:

   export default function App() {
     return (
       
         
       
     );
   }
   
   If you need to wait for auth state, keep the container mounted and change the inner navigator instead.
   

Fixes tied to findings

• If step 1 reveals a missing prefix, add the scheme to prefixes and restart the dev server.
• If step 2 shows an undefined screen, add the missing Screen component to the navigator or correct the name in the linking config.
• If step 3 finds a scheme mismatch, edit the native project files (AndroidManifest.xml or Info.plist) to match the scheme used in linking.prefixes and rebuild the native binaries.
• If step 4 shows the container unmounted, move NavigationContainer to the top level of the app tree.

Escalation criteria

Proceed to deeper investigation when:

• All checks pass but the link still does not trigger navigation.
• You see linking warnings that reference “unknown source” after verifying config.
• The app launches but navigation state does not update (check with navigation.getState() or React DevTools).
• You are using Expo managed workflow and suspect missing scheme in app.json; run expo prebuild to regenerate native files.

At this point, examine the native side:

1. Run adb logcat (Android) or device console (iOS) and look for activity start intents or URL handling logs.
2. Confirm that the intent‑filter or URL Types are correctly placed inside the <application> tag.
3. For Expo, verify scheme under ios and android in app.json and run expo run:android or expo run:ios to see the generated native configuration.

Limitations and practical verification

This guide assumes React Navigation v6 and a functional deep‑link URI (e.g., myapp://settings). It does not cover universal links (Apple App Links) or Android App Links, which require additional domain association files.

To verify a fix, repeat the link test:

• Android: adb shell am start -W -a android.intent.action.VIEW -d myapp://settings
• iOS: open the URL from Safari, Notes, or run xcrun simctl openurl booted myapp://settings on a simulator.
• Watch the screen change to the target route and optionally log navigation.getState() to confirm the state includes the expected screen name.