mWeb - Onboarding - App freezes when create new account

[jponikarchuk]

If you haven’t already, check out our contributing guidelines for onboarding and email contributors@expensify.com to request to join our Slack channel!

---

Version Number: 9.3.41-0
Reproducible in staging?: Yes
Reproducible in production?: No
If this was caught during regression testing, add the test name, ID and link from BrowserStack: https://test-management.browserstack.com/projects/2219752/test-runs/TR-10920/41236545/1264594257
Email or phone of affected tester (no customers): New account
Issue reported by: Applause Internal Team
Bug source: Regression TC Execution
Device used: Android 16 / Pixel 7A/ Chrome, iPhone 11 Safari
App Component: User Settings

Action Performed:

Preconditions:

• Use mWeb or
• Use Web but resize the browser into small screen

1. Open https://staging.new.expensify.com/
2. Start to create new account without '+'
3. Click 'Join'

Expected Result:

Onboarding flow will start

Actual Result:

App freezes and onboarding does not start.
Happen on Web Chrome if resize the window browser into small screen

Workaround:

Unknown

Platforms:

• Android: App
• Android: mWeb Chrome
• iOS: App
• iOS: mWeb Safari
• iOS: mWeb Chrome
• Windows: Chrome
• MacOS: Chrome / Safari

Screenshots/Videos

Video.mp4

View all open jobs on GitHub

[melvin-bot]

Triggered auto assignment to @mountiny (DeployBlockerCash), see https://stackoverflowteams.com/c/expensify/questions/9980/ for more details.

[melvin-bot]

💬 A slack conversation has been started in #expensify-open-source

[github-actions]

👋 Friendly reminder that deploy blockers are time-sensitive ⏱ issues! Check out the open `StagingDeployCash` deploy checklist to see the list of PRs included in this release, then work quickly to do one of the following:

1. Identify the pull request that introduced this issue and revert it.
2. Find someone who can quickly fix the issue.
3. Fix the issue yourself.

[MelvinBot]

Proposal

Please re-state the problem that we are trying to solve in this issue.

On mWeb and web with a small/narrow viewport, creating a new account causes the app to freeze completely during the onboarding flow. This reproduces on staging (v9.3.41-0) but not on production, indicating a regression introduced in the current deploy cycle.

What is the root cause of that problem?

The freeze is caused by the new OnboardingGuard navigation guard system repeatedly redirecting navigation actions to the onboarding route, combined with Onyx.set side effects triggered during each guard evaluation — creating a cascading re-render loop that locks up the JavaScript thread.

Here is the mechanism:

1. On mount, useNavigationResetOnLayoutChange dispatches navigation.reset(navigation.getState()) — this fires for all layouts as the root navigator initializes.

2. This RESET action goes through RootStackRouter.getStateForAction, which calls handleNavigationGuards() before any routing logic.

3. OnboardingGuard.evaluate checks shouldSkipOnboarding — for new users, ALL 9 conditions are false (including isNavigatingWithReplace, since RESET is not a REPLACE action), so the guard returns REDIRECT.

4. Every REDIRECT calls getOnboardingRoute() → getOnboardingInitialPath(), which has synchronous Onyx.set side effects — it writes to ONBOARDING_PURPOSE_SELECTED and ONBOARDING_COMPANY_SIZE based on the user's signup qualifier (VSB/SMB/Individual).

5. These Onyx.set calls notify subscribers — both the module-level Onyx connections in OnboardingGuard.ts (lines 66-78) and any React components using useOnyx for these keys (including the new useOnboardingStepCounter hook added in PR fix: Color: Onboarding: The status of the progress bar relies only on the use of color #80460, which subscribes to these exact keys on every onboarding page).

6. The REDIRECT generates a CommonActions.reset() via getAdaptedStateFromPath which produces routes without stable keys. Each redirect generates new route keys, causing React Navigation to unmount/remount screens rather than update them in place.

7. The screen remounts trigger new effects — including focus trap effects from FocusTrapForScreen changes (PR #79834) which add multiple useEffect/useLayoutEffect hooks and extra View wrappers. These effects, combined with the Onyx-driven re-renders, trigger additional navigation actions that re-enter the guard → more REDIRECTs → more Onyx.set side effects → infinite loop.

Why narrow layout only: Several staging-only changes are narrow-layout-specific:

• getStateWithFilteredPreloadedRoutes() only applies on narrow layouts, altering route state differently
• dismissModalWithReport branches on getIsNarrowLayout(), using navigate with forceReplace: true on narrow vs. a different path on wide — the REPLACE path bypasses the guard via isNavigatingWithReplace, but the narrow-layout path may not
• The TransitionTracker V2 removal (PR #85700) removed transition-aware deferral from navigate()/goBack()/dismissModal(), so navigation actions now fire synchronously without any throttling — this amplifies the loop on constrained devices

Why staging only: The entire guard-based navigation interception system (OnboardingGuard, RootStackRouter.handleNavigationGuards) is new in this staging release. Production uses the previous imperative navigation approach for onboarding, which doesn't have this REDIRECT loop mechanism.

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

Two targeted changes:

1. In OnboardingGuard.evaluate — skip REDIRECT when already on/heading to onboarding:

Add a check at the top of the guard's evaluation: if the current focused route is already an onboarding flow screen, return ALLOW instead of REDIRECT. This is the same pattern used by shouldPreventReset (which prevents navigating away from onboarding), but applied in the opposite direction — preventing redundant redirects to onboarding.

In OnboardingGuard.ts, inside evaluate(), before the shouldSkipOnboarding check:

• Get the current focused route from state using findFocusedRoute(state)
• If the current focused route name is an onboarding flow name (using isOnboardingFlowName()), return {type: 'ALLOW'} early

This directly breaks the re-redirect loop.

2. In getOnboardingInitialPath — remove Onyx.set side effects from the path computation:

The Onyx.set calls at lines 118-128 of OnboardingFlow.ts should not be called during synchronous guard evaluation. Move them to startOnboardingFlow() or to the onboarding page components' mount effects instead. getOnboardingInitialPath should be a pure function — it should read Onyx data but not write to it.

What alternative solutions did you explore? (Optional)

• Restoring the broader bypass from commit f5a4ecf (which was partially reverted in 45a31bc): The original fix made ALL action types bypass the guard when navigating to onboarding, but this was narrowed to only REPLACE actions. Restoring it would fix the freeze but might re-introduce whatever issue prompted the revert.
• Adding a "redirect-in-progress" flag to the guard to prevent re-entrant evaluation — this would work but is more complex and fragile than checking the current route.
• Re-introducing TransitionTracker or adding navigation batching/throttling — this would mask the symptom but not fix the root cause.

---

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

[OSBotify]

Investigation Summary

Classification: Frontend bug
Primary Causing PR: #81689 - "Create Navigation guards with OnboardingGuard & TestDriveModalGuard" by @TMisiukiewicz (High confidence)
Contributing PRs:

• #80460 - Added useOnboardingStepCounter hook that amplifies the loop
• #79834 - FocusTrap changes that add additional effects (already reverted in [CP Staging] Revert "fix: [Web] Focus restoration mechanism on back navigation (#76921)" #85887)

Recommendation: REVERT

Revert PR #81689 to remove the OnboardingGuard system, which is causing the infinite redirect loop.

The freeze happens because:

1. OnboardingGuard evaluates on every navigation action and redirects incomplete users to onboarding routes
2. The redirect calls getOnboardingInitialPath() which makes synchronous Onyx.set calls (lines 118-128 of OnboardingFlow.ts)
3. These Onyx updates trigger subscribers including useOnboardingStepCounter from PR fix: Color: Onboarding: The status of the progress bar relies only on the use of color #80460
4. The resulting re-renders trigger new navigation actions that re-enter the guard
5. This creates an infinite loop that freezes the app

Labels: This is a frontend bug affecting new account creation in the App. Keeping DeployBlockerCash label as appropriate. No label changes needed.

Detailed Analysis

Evidence

MelvinBot has provided an excellent technical analysis of the root cause. My investigation confirms:

• PR Create Navigation guards with OnboardingGuard & TestDriveModalGuard #81689 introduced the navigation guard system on 2026-02-12, which intercepts all navigation actions and redirects users who need onboarding
• The guard system is present in staging (v9.3.41-0) but was not in earlier production releases, explaining the staging-only reproduction
• PR fix: App crashes with infinite OnboardingGuard redirect loop #84699 was merged on 2026-03-10 to fix a previous infinite loop issue with OnboardingGuard, but it did not address this specific narrow-layout scenario

Verification

Files affected by the bug:

• src/libs/Navigation/guards/OnboardingGuard.ts (lines 202-220: redirect logic)
• src/libs/Navigation/AppNavigator/createRootStackNavigator/RootStackRouter.ts (lines 126-130: guard evaluation happens before routing)
• src/libs/actions/Welcome/OnboardingFlow.ts (lines 118-128: synchronous Onyx.set side effects)
• src/hooks/useOnboardingStepCounter.ts (from PR fix: Color: Onboarding: The status of the progress bar relies only on the use of color #80460: subscribes to the keys being set)

PR #81689 modifies all of these areas to implement the guard system.

Root Cause

The OnboardingGuard system has a fundamental architectural issue: it performs side effects (Onyx.set operations) during synchronous guard evaluation. This violates the principle that guards should be pure functions that only read state, not modify it.

When combined with:

• Narrow layout specific navigation logic
• The new useOnboardingStepCounter hook subscribing to the same keys
• Additional render cycles from FocusTrap changes (though now reverted)

The result is a cascading re-render loop that completely locks up the JavaScript thread.

Why Narrow Layout Only

MelvinBot correctly identified that several narrow-layout specific code paths interact differently with the guard system, including different handling in dismissModalWithReport and getStateWithFilteredPreloadedRoutes.

Why Staging Only

The entire OnboardingGuard system was introduced in this staging cycle and is not present in production, explaining the staging-only reproduction.