Repository navigation
Description
Thread here.
Problem
There are two related problems during the onboarding flow:
1. Navigation loop on onboarding modals
When signing up with a "Manage Team" path (10+ employees), the onboarding modal can get stuck in a loop, cycling between steps (e.g., repeatedly showing the accounting software selection screen) instead of progressing to completion. The loop prevents the user from reaching the Test Drive step. Refreshing the page breaks the loop and allows onboarding to continue.
This has been observed by multiple users and appears to be intermittent -- subsequent signups with the same flow may work fine.
2. "Unexpected error" on onboarding tasks after refresh
After refreshing to escape the loop, the onboarding tasks (Guided Setup) display "Unexpected error posting the comment. Please try again later." This happens because the OPEN_REPORT request carrying guidedSetupData either fails or is interrupted by the refresh, causing the failure data to be applied to each task's report action.
Likely Root Cause
The loop is most likely caused by a race condition in getOnboardingInitialPath() in src/libs/actions/Welcome/OnboardingFlow.ts:
- When the
OnboardingGuardruns on navigation, it callsgetOnboardingInitialPath()to determine where to redirect. - The guard checks whether
onboardingPurposeSelectedandonboardingCompanySizematch the current path. IfonboardingInitialPathpoints to/onboarding/employeesor/onboarding/accountingbut the purpose/company-size Onyx values are stale or not yet persisted, the guard redirects back to/onboarding/purpose. - On the next navigation event, the guard runs again with the same stale state, creating a redirect loop.
- The
ONBOARDING_LAST_VISITED_PATHkey (updated insrc/libs/Navigation/NavigationRoot.tsx) may also contribute by persisting a path that triggers the redirect cycle.
The task errors come from failure handling in prepareOnboardingOnyxData() in src/libs/ReportUtils.ts, which applies report.genericAddCommentFailureMessage to each task report action when the OPEN_REPORT request fails.
Key Files
src/libs/actions/Welcome/OnboardingFlow.ts-getOnboardingInitialPath()redirect logicsrc/libs/Navigation/guards/OnboardingGuard.ts- Guard that triggers redirectssrc/libs/Navigation/NavigationRoot.tsx- UpdatesONBOARDING_LAST_VISITED_PATHsrc/pages/OnboardingAccounting/BaseOnboardingAccounting.tsx- Accounting step (where loop was observed)src/libs/ReportUtils.ts-prepareOnboardingOnyxData()failure handlingsrc/libs/actions/Report/index.ts-getGuidedSetupDataForOpenReport()
Steps to Reproduce
- Create a new account on web
- Choose "Manage a team" purpose
- Select "10+" employees (or possibly other sizes)
- Progress through onboarding modals
- Observe the modal may loop (cycling back to accounting or earlier steps) instead of progressing to Test Drive
- Refresh the page to break the loop
- Observe onboarding tasks now show "Unexpected error posting the comment"
Note: This is intermittent and may not reproduce on every attempt.
Expected Behavior
- Onboarding modals should progress linearly without looping
- If a refresh is needed, onboarding tasks should not show errors (the guided setup request should be retried or errors should be cleared)
Platforms
- Web (confirmed)
- Mobile (not yet confirmed)
Issue Owner
Current Issue Owner: @linhvovan29546Upwork Automation - Do Not Edit
- Upwork Job URL: https://www.upwork.com/jobs/~022033637307162175700
- Upwork Job ID: 2033637307162175700
- Last Price Increase: 2026-03-16
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
MelvinBot commentedon Mar 16, 2026
Proposal
Please re-state the problem that we are trying to solve in this issue.
Two related problems during onboarding:
What is the root cause of that problem?
Problem 1 — Navigation Loop (Race Condition in OnboardingGuard)
The
OnboardingGuard(OnboardingGuard.ts:104-114) runs synchronously during every navigation action viaRootStackRouter.getStateForAction. It reads onboarding state (onboardingPurposeSelected,onboardingCompanySize,onboardingInitialPath) from module-level variables populated byOnyx.connectWithoutViewcallbacks (OnboardingGuard.ts:66-85).The problem: these callbacks fire on the next macrotask (via
setTimeout(0)in Onyx'sprepareSubscriberUpdate), not synchronously. When onboarding pages callOnyx.setthenNavigation.navigatein the same tick — e.g.,BaseOnboardingEmployees.tsx:67-68callssetOnboardingCompanySize(size)thenNavigation.navigate(ONBOARDING_ACCOUNTING)— the guard evaluates before the Onyx callback updatesonboardingCompanySize.Additionally,
ONBOARDING_LAST_VISITED_PATHis updated inonStateChange(NavigationRoot.tsx:61-65) which fires after navigation completes, but the guard runs duringgetStateForAction— before navigation completes. SoonboardingInitialPathalways reflects the previous page, not the target. The fallback atOnboardingFlow.ts:162returns this stale path, which can redirect the user back to their current page instead of allowing forward progress.On page refresh, the same issue manifests differently:
ONBOARDING_LAST_VISITED_PATHmay load from storage beforeONBOARDING_COMPANY_SIZE, causing the condition atOnboardingFlow.ts:155-160to fire (sincecompanySizeisnullwhile the path points to accounting), redirecting to Purpose and restarting the cycle.Problem 2 — Task Errors After Refresh
prepareOnboardingOnyxData()inReportUtils.ts:11884-11908builds failure data that setserrors: getMicroSecondOnyxErrorWithTranslationKey('report.genericAddCommentFailureMessage')on every onboarding task's report action. The optimistic data (task reports,hasCompletedGuidedSetupFlow: true,isInviteOnboardingComplete: true) is applied immediately and persisted to storage before the API request is sent (API/index.ts:79-82). When the user refreshes mid-flight, the in-flight OPEN_REPORT request is killed. On reload,SequentialQueueretries it (SequentialQueue.ts:437), and if it eventually fails, the failure data is applied (SequentialQueue.ts:252), decorating every task with the error message.Critically,
isInviteOnboardingCompleteis set totrueoptimistically (Report/index.ts:1266-1271) but is not reverted in the failure data (ReportUtils.ts:12079-12089), preventing guided setup from being re-attempted and leaving the user permanently stuck with error-decorated tasks.What changes do you think we should make in order to solve the problem?
Fix 1 — Navigation Loop: In the onboarding page components (
BaseOnboardingEmployees.tsx,BaseOnboardingPurpose.tsx), await theOnyx.setpromise before callingNavigation.navigate. SinceOnyx.setreturns a promise, awaiting it ensures the guard sees updated values when navigation triggers. TheonPresshandlers should become async:This should be applied to all onboarding pages that call
Onyx.setfollowed by navigation (Purpose, Employees, and any others with the same pattern).Fix 2 — Task Errors: In the failure data returned by
getGuidedSetupDataForOpenReport()(Report/index.ts), also revertisInviteOnboardingCompletetofalseso thatgetGuidedSetupDataForOpenReportcan re-attempt the guided setup on subsequentopenReport()calls instead of being permanently blocked by the guard at line 1231.What alternative solutions did you explore? (Optional)
For the navigation loop, alternatives considered:
connectWithoutViewcallbacks in the guard — this would get synchronously-updated values, but there's no clean public API for synchronous cache reads.getOnboardingInitialPath(). This is less precise but avoids the timing issue entirely.ONBOARDING_LAST_VISITED_PATHin the guard itself before evaluating — this would fix the lag but mixes concerns between the guard and navigation state management.Next Steps for Contributor+ team: Reply with
@MelvinBot implement thisto create a draft PR,@MelvinBot <your feedback>to refine this analysis, or explain why you are rejecting Melvin's proposal.melvin-bot commentedon Mar 16, 2026
Triggered auto assignment to Contributor-plus team member for initial proposal review - @linhvovan29546 (
External)melvin-bot commentedon Mar 16, 2026
Job added to Upwork: https://www.upwork.com/jobs/~022033637307162175700
[-]Onboarding modals can get stuck in a navigation loop, and refreshing to escape causes tasks to show "unexpected error"[/-][+][$250] Onboarding modals can get stuck in a navigation loop, and refreshing to escape causes tasks to show "unexpected error"[/+]shivang-goliyan commentedon Mar 16, 2026
Proposal
Please re-state the problem that we are trying to solve in this issue.
Two problems during onboarding: (1) the modal screens can get stuck in a redirect loop, cycling between steps instead of progressing — observed on the "Manage Team" path with 10+ employees. (2) After refreshing to break the loop, all onboarding tasks show "Unexpected error posting the comment" and can't recover.
What is the root cause of that problem?
Problem 1 — Navigation Loop:
The onboarding page handlers call their Onyx setter (e.g.
setOnboardingCompanySize()) as fire-and-forget, then immediately callNavigation.navigate(). The setter functions inWelcome/index.ts(lines 40-50) don't return theOnyx.set()promise.When
OnboardingGuard.evaluate()runs duringgetStateForAction, it reads module-level variables populated byconnectWithoutViewcallbacks (OnboardingGuard.ts:66-85). These callbacks haven't fired yet because Onyx flushes them asynchronously. So whengetOnboardingInitialPath()checkscurrentOnboardingCompanySizeatOnboardingFlow.ts:155-157, it's stillnull, and the condition(currentOnboardingCompanySize === null && currentOnboardingPurposeSelected !== null)redirects the user back to/onboarding/purpose— creating the loop.All three onboarding pages have this same fire-and-forget pattern:
BaseOnboardingEmployees.tsx:67-68,BaseOnboardingPurpose.tsx:93-96, andBaseOnboardingAccounting.tsx:185-188.Problem 2 — Task Errors After Refresh:
The failure data in
prepareOnboardingOnyxData()(ReportUtils.ts:12079-12089) resetschoice,createWorkspace,addExpenseApprovals,setupCategoriesAndTags, andsetupTags— but omitsisInviteOnboardingComplete: false. Since the optimistic data sets it totrueatReport/index.ts:1269, a failed or interruptedOPEN_REPORTrequest leaves the flag permanentlytrue, which blocksgetGuidedSetupDataForOpenReport()at line 1231 from ever retrying. The tasks stay decorated with the error message.What changes do you think we should make in order to solve the problem?
Fix 1: In
BaseOnboardingEmployees.tsx,BaseOnboardingPurpose.tsx, andBaseOnboardingAccounting.tsx, wrap theNavigation.navigate()calls inNavigation.setNavigationActionToMicrotaskQueue()after calling the Onyx setter. This defers navigation until Onyx callbacks have propagated. The codebase already uses this exact pattern inupdateOnboardingValuesAndNavigation()atWelcome/index.ts:68-74, with the comment "We need to have the Onyx values updated before navigating back."For example in
BaseOnboardingEmployees.tsx:Fix 2: Add
isInviteOnboardingComplete: falseto theNVP_INTRO_SELECTEDfailure data object atReportUtils.ts:12082, so guided setup can retry after an API failure.What alternative solutions did you explore? (Optional)
I considered making the setter functions return the
Onyx.set()promise and awaiting them in asynconPresshandlers — this gives the strongest correctness guarantee but async event handlers in React Native can cause unhandled rejections if the component unmounts during the await.setNavigationActionToMicrotaskQueueis purpose-built for this timing problem and already proven in the codebase.I also looked at bypassing the guard for intra-onboarding
NAVIGATE/PUSHactions, but commit45a31bc9c59explicitly reverted that approach (originally added inf5a4ecf0c1d), so the team has already considered and rejected it.fix: resolve onboarding navigation loop and task errors (Expensify#85454
14 remaining items
TMisiukiewicz commentedon Apr 1, 2026
Alright I was able to figure out the exact repro steps:
@gmail.comdomainLooking for the root cause
TMisiukiewicz commentedon Apr 1, 2026
@linhvovan29546 PR with a fix: #86856
However I think this is different bug than the one posted here - I still believe the original bug reported in this issue was fixed by #84699
linhvovan29546 commentedon Apr 1, 2026
@TMisiukiewicz I see that this PR applies a similar fix to #86856, and I can’t reproduce the crash on that build. So I think that PR resolves the issue.
TMisiukiewicz commentedon Apr 1, 2026
looks good, can you confirm that on this branch the Home screen is visible under the modal? This is something I stumbled upon when looking for a proper fix, so if it covers this scenario I am happy to close my PR in favor of this one
linhvovan29546 commentedon Apr 1, 2026
I’m not sure which issue you’re referring to. You can test it here: https://86390.pr-testing.expensify.com
Screen.Recording.2026-04-01.at.21.52.15.mov
TMisiukiewicz commentedon Apr 2, 2026
@linhvovan29546 everything looks good, so I think I can close my PR in favor of #86390 👍
melvin-bot commentedon Apr 24, 2026
This issue has not been updated in over 15 days. @TMisiukiewicz, @linhvovan29546 eroding to Monthly issue.
P.S. Is everyone reading this sure this is really a near-term priority? Be brave: if you disagree, go ahead and close it out. If someone disagrees, they'll reopen it, and if they don't: one less thing to do!
dominictb commentedon May 1, 2026
@linhvovan29546 Are you due payment here?
linhvovan29546 commentedon May 1, 2026
@dominictb No, I haven’t reviewed PR yet, the issue was resolved elsewhere