Onboarding - Onboarding does not appear until user clicks on any tab

[applause-bot]

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.89-1
Reproducible in staging?: Yes
Reproducible in production?: No
If this was caught during regression testing, add the test name, ID and link from BrowserStack: #91796
Email or phone of affected tester (no customers): sdjsodnjiodsjsoinj1@gmail.com
Issue reported by: Applause Internal Team
Bug source: Exploratory - Significant User Experience Deterioration
Device used: Mac 26.5 / Chrome
App Component: Other

Action Performed:

1. Go to staging.new.expensify.com
2. Log in with a new Gmail account.
3. Click any tab (eg, Inbox).

Expected Result:

Onboarding will open after logging in with a new account.

Actual Result:

Onboarding does not appear until user clicks on any tab.

Workaround:

Unknown

Platforms:

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

Screenshots/Videos

Bug7165785_1780003411857.1.mp4

View all open jobs on GitHub

Applause Internal Information
Exported by: Svetlana Lazutkina
Bug ID: 7165785

[applause-bot]

While Applause doesn't embed attachments for this bug, here are the links for quick view:
https://platform.applause.com/services/links/v1/external/aa07e31a9ece34ab4d3244c9f845d4dfc29b78133e6713840008c13d48c43012

[melvin-bot]

You have been assigned to this deploy blocker because you recently merged this PR: #91796

[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

What is the root cause of that problem?

PR #91796 added an extra gate inside navContainsProtectedRoutes() so that it now also requires TabNavigator's nested state to be stale === false via isTabNavigatorReady.

TabNavigator is registered with getComponent (lazy require) in AuthScreens.tsx:186-190, so React Navigation does not instantiate its child router (and does not populate a non-stale nested state) until the tab is actually focused.

For a fresh login, the onboarding flow runs at useOnboardingFlow.ts:95-108:

Navigation.waitForProtectedRoutes().then(() => startOnboardingFlow({...}));

After PR #91796, the initial check inside waitForProtectedRoutes() fails (TabNavigator nested state is still stale), and no subsequent root 'state' event satisfies navContainsProtectedRoutes because TabNavigator is lazy and never gets focused. The promise hangs indefinitely, so startOnboardingFlow never runs. The moment the user clicks any tab, TabNavigator's component is required, useNavigationBuilder runs, the nested state flips to stale: false, the listener finally matches, the promise resolves, and onboarding appears.

The subscribe.ts change from the same PR is unrelated — onboarding is dispatched in-JS via navigationRef.resetRoot, not delivered via Linking.addEventListener.

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

Decouple the "TabNavigator is mounted enough to dispatch nested NAVIGATE actions" gate from navContainsProtectedRoutes. The original waitForProtectedRoutes consumers (like the onboarding hook) only need to know that protected screens have been declared on the root navigator — they do not need TabNavigator's child router to have already run, because they navigate via resetRoot rather than nested NAVIGATE.

Recommended approach: revert the extra return isTabNavigatorReady(state) line inside navContainsProtectedRoutes so the onboarding gate behaves as before, and keep the isTabNavigatorReady check only at the deep-link forwarding site in subscribe.ts:32-44, which is where the original "unhandled NAVIGATE" error from #91777 actually occurred. The deep-link path that #91796 was protecting (openReportFromDeepLink) already runs through its own waitForProtectedRoutes consumer and can keep its protection at the URL boundary.

If the deep-link consumer specifically needs the TabNavigator-ready guarantee, introduce a separate helper (e.g. waitForTabNavigatorReady()) chained after waitForProtectedRoutes() at just that call site, rather than tightening the global gate.

What alternative solutions did you explore? (Optional)

• Eager-load TabNavigator by switching its registration from getComponent to component in AuthScreens.tsx. This would make the new gate pass synchronously, but it costs startup performance for every signed-in user just to unblock onboarding.
• Make isTabNavigatorReady treat "no nested state yet" as ready (only block when stale === true). Risky — this re-opens the original race PR Wait for TabNavigator mount before resolving waitForProtectedRoutes #91796 was fixing.

Investigation details

Data flow on fresh login (post-PR #91796):

1. New user logs in; Onyx hydrates.
2. AuthScreens mounts → useOnboardingFlowRouter reads isOnboardingCompleted === false.
3. Calls Navigation.waitForProtectedRoutes().then(startOnboardingFlow).
4. Initial check: routeNames.includes(CONCIERGE) ✅, but tabRoute.state.stale === false ❌ → returns false.
5. addListener('state', ...) waits. No state change satisfies the gate because TabNavigator was registered lazily and has not been focused.
6. User clicks Inbox → TabNavigator's lazy module loads → child router runs useNavigationBuilder → nested state becomes non-stale → next state event passes the gate → promise resolves → onboarding modal finally appears.

Why this only reproduces in staging, not production: PR #91796 was merged 2026-05-27 and is in staging 9.3.89-1 only; production has not yet picked it up.

Why the existing subscribe.ts change is fine: It guards Linking.addEventListener('url', ...) callbacks — i.e., URL events delivered while the app is running. New-user onboarding is not triggered through that path; startOnboardingFlow calls navigationRef.resetRoot directly in OnboardingFlow.ts:85-100.

Related open issues:

• [$250] TabNavigator NAVIGATE action not handled during deep link login flow #91777 — the original deep-link race that PR Wait for TabNavigator mount before resolving waitForProtectedRoutes #91796 was fixing.
• Onboarding - Old UI briefly appears after page reload #90284 — "Onboarding - Old UI briefly appears after page reload" (likely a different cause but same surface area).
• [$250] Onboarding - Not here page appears briefly after completing onboarding #91437 — "Not here page appears briefly after completing onboarding" (different flow, post-onboarding).
• [$250] After signing in with a new account, the home page appears instead of the room #85242 — "After signing in with a new account, the home page appears instead of the room" (older, possibly related to the onboarding entry flow).

---

Next Steps for Contributor+ team:
To accept: @MelvinBot implement this to create a draft PR.
To refine: @MelvinBot <your feedback>
To reject: Explain why you are rejecting Melvin's proposal.