War Story: Debugging a React Native 0.73 Navigation Bug for Our iOS and Android Apps

// AppNavigator.tsx - Original navigation configuration that triggered the 0.73 bug
// Dependencies (exact versions that reproduced the crash):
// react-native: 0.73.0
// @react-navigation/native: 6.1.2
// @react-navigation/native-stack: 6.9.2
// react-native-screens: 3.20.0
// react-native-safe-area-context: 4.5.0

import React, { useEffect, useState } from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { StatusBar } from 'expo-status-bar';
import { View, Text, ActivityIndicator, LogBox } from 'react-native';
import { SafeAreaProvider } from 'react-native-safe-area-context';

// Screens
import AuthScreen from './screens/AuthScreen';
import HomeScreen from './screens/HomeScreen';
import TransactionScreen from './screens/TransactionScreen';
import ProfileScreen from './screens/ProfileScreen';
import SettingsScreen from './screens/SettingsScreen';
import { UserProvider } from './context/UserContext';

// Ignore non-critical warnings for brevity, but log them for debugging
LogBox.ignoreLogs(['Warning: ...']); // We later found this hid the navigation warning causing the crash

const AuthStack = createNativeStackNavigator();
const MainStack = createNativeStackNavigator();
const SettingsStack = createNativeStackNavigator();

// Nested Settings Stack - this is where the bug triggered
const SettingsNavigator = () => {
  return (




  );
};

// Main App Stack with nested Profile > Settings flow
const MainNavigator = () => {
  return (




      {/* Nested Settings Navigator rendered as a screen in Main Stack */}


  );
};

const App = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [user, setUser] = useState(null);

  // Simulate auth check on app launch
  useEffect(() => {
    const checkAuth = async () => {
      try {
        const storedUser = await AsyncStorage.getItem('user');
        if (storedUser) {
          setUser(JSON.parse(storedUser));
        }
      } catch (error) {
        console.error('Auth check failed:', error);
        // Error handling: log to Sentry, don't crash the app
        Sentry.captureException(error);
      } finally {
        // Add 1.5s delay to simulate splash screen, which exacerbated the race condition
        setTimeout(() => setIsLoading(false), 1500);
      }
    };
    checkAuth();
  }, []);

  if (isLoading) {
    return (


        Loading your account...

    );
  }

  return (


         {
            // Log navigation state for debugging - we later found the state was corrupt here
            console.log('Navigation State:', JSON.stringify(state));
          }}
        >

            {user ? (

            ) : (

            )}





  );
};

export default App;

// navigation-bug-repro.ts - Script to reproduce and benchmark the 0.73 navigation crash
// Dependencies:
// detox: 20.0.3
// jest: 29.7.0
// react-native: 0.73.0

import { device, element, by, expect } from 'detox';
import { performance } from 'perf_hooks';
import axios from 'axios';
import * as Sentry from '@sentry/react-native';

// Configuration for repro runs
const REPRO_RUNS = 1000; // Run 1000 back press sequences to get statistically significant results
const BACK_PRESS_DELAY = 100; // Delay between back presses (ms) to trigger race condition
const CRASH_ENDPOINT = 'https://our-sentry-endpoint.com/api/crashes'; // Internal crash reporting endpoint

// Helper to check if the app is still running (not crashed)
const isAppRunning = async () => {
  try {
    // Detox method to check if the app is in the foreground
    const isVisible = await element(by.id('home-screen')).isVisible();
    return isVisible;
  } catch (error) {
    // If element not found, app likely crashed
    console.error('App not running:', error);
    return false;
  }
};

// Helper to report crash to internal analytics
const reportCrash = async (runId: number, error: any) => {
  try {
    await axios.post(CRASH_ENDPOINT, {
      runId,
      error: error.message,
      stack: error.stack,
      navVersion: '6.1.2',
      rnVersion: '0.73.0',
      timestamp: new Date().toISOString(),
    });
  } catch (reportError) {
    console.error('Failed to report crash:', reportError);
    Sentry.captureException(reportError);
  }
};

describe('React Native 0.73 Navigation Bug Repro', () => {
  beforeAll(async () => {
    await device.launchApp({
      newInstance: true,
      delete: true, // Delete app data to start fresh
    });
  });

  beforeEach(async () => {
    await device.reloadReactNative(); // Reload RN context before each run
  });

  it(`runs ${REPRO_RUNS} back press sequences to measure crash rate`, async () => {
    let crashCount = 0;
    let totalLatency = 0;
    const results = [];

    for (let i = 0; i < REPRO_RUNS; i++) {
      const runStart = performance.now();
      try {
        // Navigate to Profile > Settings to set up the crash scenario
        await element(by.id('profile-tab')).tap();
        await element(by.id('settings-button')).tap();

        // Wait for settings screen to load
        await expect(element(by.id('settings-screen'))).toBeVisible();

        // Press back twice quickly - this triggers the race condition
        await device.pressBack();
        await new Promise((resolve) => setTimeout(resolve, BACK_PRESS_DELAY));
        await device.pressBack();

        // Check if app is still running
        const isRunning = await isAppRunning();
        if (!isRunning) {
          crashCount++;
          const runEnd = performance.now();
          totalLatency += runEnd - runStart;
          results.push({ run: i, crashed: true, latency: runEnd - runStart });
          await reportCrash(i, new Error('App crashed on back press'));
          // Relaunch app after crash
          await device.launchApp({ newInstance: true });
        } else {
          const runEnd = performance.now();
          totalLatency += runEnd - runStart;
          results.push({ run: i, crashed: false, latency: runEnd - runStart });
        }
      } catch (error) {
        crashCount++;
        await reportCrash(i, error);
        results.push({ run: i, crashed: true, latency: performance.now() - runStart });
        await device.launchApp({ newInstance: true });
      }
    }

    // Calculate benchmarks
    const crashRate = (crashCount / REPRO_RUNS) * 100;
    const avgLatency = totalLatency / REPRO_RUNS;

    // Log results to console and Sentry
    console.log(`Repro Results (${REPRO_RUNS} runs):`);
    console.log(`Crash Rate: ${crashRate.toFixed(2)}%`);
    console.log(`Average Latency per Run: ${avgLatency.toFixed(2)}ms`);
    console.log(`Total Crashes: ${crashCount}`);

    Sentry.captureMessage('Navigation Bug Repro Results', {
      extra: {
        crashRate,
        avgLatency,
        crashCount,
        reproRuns: REPRO_RUNS,
        rnVersion: '0.73.0',
        navVersion: '6.1.2',
      },
    });

    // Assert that crash rate is above 0% (reproduced the bug)
    expect(crashRate).toBeGreaterThan(0);
    // Our production crash rate was 12% iOS, 9% Android - repro should match
    expect(crashRate).toBeGreaterThan(8);
  });
});

// FixedAppNavigator.tsx - Patched navigation config to resolve 0.73 race condition
// Updated dependencies:
// react-native: 0.73.0
// @react-navigation/native: 6.1.3 (patched version)
// @react-navigation/native-stack: 6.9.3 (patched version)
// react-native-screens: 3.21.0 (fixes Fabric renderer race condition)

import React, { useEffect, useState, useRef } from 'react';
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { StatusBar } from 'expo-status-bar';
import { View, Text, ActivityIndicator, LogBox, BackHandler } from 'react-native';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import * as Sentry from '@sentry/react-native';

// Screens (same as before)
import AuthScreen from './screens/AuthScreen';
import HomeScreen from './screens/HomeScreen';
import TransactionScreen from './screens/TransactionScreen';
import ProfileScreen from './screens/ProfileScreen';
import SettingsScreen from './screens/SettingsScreen';
import { UserProvider } from './context/UserContext';

// Ignore non-critical warnings, but enable navigation warnings for debugging
LogBox.ignoreLogs(['Non-critical warning']);
LogBox.ignoreLogs(['Warning: Cannot update a component']); // This was the warning we missed earlier

const AuthStack = createNativeStackNavigator();
const MainStack = createNativeStackNavigator();
const SettingsStack = createNativeStackNavigator();

// Fix 1: Add back press handler to prevent rapid back presses
const useBackPressHandler = (navigationRef: any) => {
  useEffect(() => {
    const backHandler = BackHandler.addEventListener('hardwareBackPress', () => {
      const currentRoute = navigationRef.getCurrentRoute();
      // Prevent back press if navigation state is still transitioning
      if (navigationRef.isTransitioning) {
        console.log('Ignoring back press: navigation transitioning');
        return true; // Prevent default back press
      }
      // Allow back press for non-nested stacks
      if (currentRoute?.name === 'SettingsMain') {
        // Add 300ms delay to prevent race condition with Fabric renderer
        setTimeout(() => {
          navigationRef.goBack();
        }, 300);
        return true;
      }
      return false; // Let default back press handle it
    });

    return () => backHandler.remove();
  }, [navigationRef]);
};

// Fixed Settings Navigator: removed conflicting animation configs
const SettingsNavigator = () => {
  const navigationRef = useNavigationContainerRef();
  useBackPressHandler(navigationRef);

  return (




  );
};

// Fixed Main Navigator: aligned animation configs across stacks
const MainNavigator = () => {
  const navigationRef = useNavigationContainerRef();
  useBackPressHandler(navigationRef);

  return (






  );
};

const App = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [user, setUser] = useState(null);
  const navigationRef = useNavigationContainerRef();

  // Fix 5: Added navigation state validation to prevent corrupt state crashes
  const validateNavigationState = (state: any) => {
    try {
      if (!state || !state.routes) {
        throw new Error('Invalid navigation state: missing routes');
      }
      // Check for duplicate route keys (corrupt state indicator)
      const routeKeys = state.routes.map((r: any) => r.key);
      const hasDuplicates = new Set(routeKeys).size !== routeKeys.length;
      if (hasDuplicates) {
        throw new Error('Corrupt navigation state: duplicate route keys');
      }
    } catch (error) {
      console.error('Navigation state validation failed:', error);
      Sentry.captureException(error);
      // Reset navigation state to default
      navigationRef.reset({
        index: 0,
        routes: [{ name: user ? 'Main' : 'Auth' }],
      });
    }
  };

  useEffect(() => {
    const checkAuth = async () => {
      try {
        const storedUser = await AsyncStorage.getItem('user');
        if (storedUser) {
          setUser(JSON.parse(storedUser));
        }
      } catch (error) {
        console.error('Auth check failed:', error);
        Sentry.captureException(error);
      } finally {
        // Fix 6: Reduced splash screen delay to minimize race condition window
        setTimeout(() => setIsLoading(false), 500);
      }
    };
    checkAuth();
  }, []);

  if (isLoading) {
    return (


        Loading your account...

    );
  }

  return (


         {
            // Validate navigation state on every change
            validateNavigationState(state);
            console.log('Navigation State Updated:', JSON.stringify(state));
          }}
        >

            {user ? (

            ) : (

            )}





  );
};

export default App;

// package.json - Pinned dependencies to prevent version drift
{
  "dependencies": {
    "react-native": "0.73.0",
    "@react-navigation/native": "6.1.3",
    "@react-navigation/native-stack": "6.9.3",
    "react-native-screens": "3.21.0",
    "react-native-safe-area-context": "4.5.0"
  },
  "devDependencies": {
    "detox": "20.0.3",
    "jest": "29.7.0"
  }
}

// Navigation state validation helper
const validateNavigationState = (state: any) => {
  if (!state?.routes) {
    throw new Error('Invalid navigation state: missing routes');
  }
  const routeKeys = state.routes.map((r: any) => r.key);
  if (new Set(routeKeys).size !== routeKeys.length) {
    throw new Error('Corrupt state: duplicate route keys');
  }
  if (state.index < 0 || state.index >= state.routes.length) {
    throw new Error('Invalid state index');
  }
};

// Back press debounce handler
const useBackPressHandler = (navigationRef: any) => {
  useEffect(() => {
    const backHandler = BackHandler.addEventListener('hardwareBackPress', () => {
      if (navigationRef.isTransitioning) {
        return true; // Ignore back press during transition
      }
      // Debounce back press by 300ms
      const timeout = setTimeout(() => navigationRef.goBack(), 300);
      return true;
    });
    return () => {
      backHandler.remove();
      clearTimeout(timeout);
    };
  }, [navigationRef]);
};