[Due for payment 2026-04-28] [$250] iOS crash: Infinite onboarding navigation loop (Maximum update depth exceeded)

[mountiny]

Problem

Users on iOS production are hitting an infinite navigation loop crash during the onboarding flow. The app crashes with "Maximum update depth exceeded" (React error).

Sentry issue: https://expensify.sentry.io/issues/7332234716/

Symptoms

• Rapid, repeated navigation to OnboardingModalNavigator visible in Sentry breadcrumbs
• VL logs show [OnboardingGuard] Redirecting to onboarding route firing repeatedly with all boolean conditions as empty strings (serialized false/undefined)
• Not reproducible locally — appears to require a specific timing/state combination

Root Cause

The OnboardingGuard in src/libs/Navigation/guards/OnboardingGuard.ts lacks idempotency. When shouldSkipOnboarding is false, the guard unconditionally returns a REDIRECT to the onboarding route — even when the user is already on the OnboardingModalNavigator.

Each REDIRECT produces a CommonActions.reset() that changes the navigation state, which triggers:

1. onStateChange in NavigationRoot.tsx → Onyx writes (updateOnboardingLastVisitedPath)
2. Re-renders from Onyx state changes
3. Re-evaluation of the guard (via useNavigationBuilder calling router.getStateForAction during render)
4. Another REDIRECT → another reset → loop continues until React hits maximum update depth

Additionally, getOnboardingInitialPath() (called by the guard to compute the redirect route) performs Onyx.set() side effects for certain user types (VSB, SMB, individual), which injects further state mutations into each loop iteration.

Fix

Add an idempotency check: if OnboardingModalNavigator is already present in state.routes, return ALLOW instead of issuing a redundant REDIRECT. This ensures the guard reaches a stable state after the first redirect.

Platform

• iOS
• Android
• Web
• Desktop
• Mobile Web

Issue Owner

Current Issue Owner: @mallenexpensify

Issue Owner

Current Issue Owner: @mallenexpensify

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022044575911073373513
• Upwork Job ID: 2044575911073373513
• Last Price Increase: 2026-04-16

[MelvinBot]

Proposal

What is the root cause of that problem?

The OnboardingGuard (OnboardingGuard.ts:162-221) lacks an idempotency check. When shouldSkipOnboarding is false, it unconditionally returns REDIRECT to the onboarding route — even when OnboardingModalNavigator is already present in state.routes.

Each REDIRECT is converted to a CommonActions.reset() in RootStackRouter.ts:96-108. The resulting state change triggers two sources of Onyx mutations that cause re-renders and re-evaluation of the guard:

1. NavigationRoot.tsx onStateChange (line 62-66) calls updateOnboardingLastVisitedPath(), which writes Onyx.merge(ONBOARDING_LAST_VISITED_PATH) — a key the guard subscribes to.
2. getOnboardingInitialPath() (OnboardingFlow.ts:118-128) fires Onyx.set() calls for VSB/SMB/Individual user types on every guard evaluation, injecting additional state mutations per iteration.

These Onyx writes trigger re-renders → new navigation dispatches → guard re-evaluation → another REDIRECT → loop until React hits "Maximum update depth exceeded."

The existing shouldPreventReset check (line 116-131) does not catch this case because it only blocks resets away from onboarding (current=onboarding, target≠onboarding), not redundant resets to onboarding.

What changes do you think we should make in order to solve the problem?

Add an idempotency check at the top of OnboardingGuard.evaluate(): before returning REDIRECT, check if OnboardingModalNavigator is already in state.routes. If it is, return ALLOW instead. This ensures the guard reaches a stable state after the first redirect.

In OnboardingGuard.ts, before the final REDIRECT return (around line 217), add a check like:

If state.routes already contains a route with name === NAVIGATORS.ONBOARDING_MODAL_NAVIGATOR, return {type: 'ALLOW'}.

This is a minimal, safe fix — the guard still redirects to onboarding when needed, but won't issue redundant redirects when the user is already there.

What alternative solutions did you explore? (Optional)

1. Move Onyx.set() calls out of getOnboardingInitialPath() — this would reduce the side effects but wouldn't fully prevent the loop since updateOnboardingLastVisitedPath would still cause re-renders. Could be done as a follow-up improvement.
2. Add the check to shouldPreventReset — this would only catch the RESET action path but not other action types that could trigger the guard. The idempotency check on state.routes is more robust.

Possibly related issue

Expensify/App#85454 — "Onboarding modals can get stuck in a navigation loop" — describes a similar symptom where onboarding gets stuck in a loop. The same root cause (missing idempotency check) likely contributes to that issue as well.

---

Next Steps for Contributor+ team: Reply with @MelvinBot implement this to create a draft PR, @MelvinBot <your feedback> to refine this analysis, or explain why you are rejecting Melvin's proposal.

[melvin-bot]

Current assignee @Krishna2323 is eligible for the External assigner, not assigning anyone new.

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~022044575911073373513