Skip to content

[$250] Onboarding modals can get stuck in a navigation loop, and refreshing to escape causes tasks to show "unexpected error" #85454

Closed

Description

@mountiny

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 OnboardingGuard runs on navigation, it calls getOnboardingInitialPath() to determine where to redirect.
  • The guard checks whether onboardingPurposeSelected and onboardingCompanySize match the current path. If onboardingInitialPath points to /onboarding/employees or /onboarding/accounting but 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_PATH key (updated in src/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

Steps to Reproduce

  1. Create a new account on web
  2. Choose "Manage a team" purpose
  3. Select "10+" employees (or possibly other sizes)
  4. Progress through onboarding modals
  5. Observe the modal may loop (cycling back to accounting or earlier steps) instead of progressing to Test Drive
  6. Refresh the page to break the loop
  7. 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 OwnerCurrent Issue Owner: @linhvovan29546
Upwork Automation - Do Not Edit
  • Upwork Job URL: https://www.upwork.com/jobs/~022033637307162175700
  • Upwork Job ID: 2033637307162175700
  • Last Price Increase: 2026-03-16

Activity

  1. added
    BugSomething is broken. Auto assigns a BugZero manager.
    on Mar 16, 2026
  2. MelvinBot commented on Mar 16, 2026

    @MelvinBot
    Contributor

    Proposal

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

    Two related problems during onboarding:

    1. Navigation loop: When signing up via "Manage Team" (10+ employees), the onboarding modals can get stuck cycling between steps (e.g., repeatedly showing accounting selection) instead of progressing. Refreshing breaks the loop.
    2. Task errors after refresh: After refreshing, onboarding tasks show "Unexpected error posting the comment. Please try again later."

    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 via RootStackRouter.getStateForAction. It reads onboarding state (onboardingPurposeSelected, onboardingCompanySize, onboardingInitialPath) from module-level variables populated by Onyx.connectWithoutView callbacks (OnboardingGuard.ts:66-85).

    The problem: these callbacks fire on the next macrotask (via setTimeout(0) in Onyx's prepareSubscriberUpdate), not synchronously. When onboarding pages call Onyx.set then Navigation.navigate in the same tick — e.g., BaseOnboardingEmployees.tsx:67-68 calls setOnboardingCompanySize(size) then Navigation.navigate(ONBOARDING_ACCOUNTING) — the guard evaluates before the Onyx callback updates onboardingCompanySize.

    Additionally, ONBOARDING_LAST_VISITED_PATH is updated in onStateChange (NavigationRoot.tsx:61-65) which fires after navigation completes, but the guard runs during getStateForAction — before navigation completes. So onboardingInitialPath always reflects the previous page, not the target. The fallback at OnboardingFlow.ts:162 returns 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_PATH may load from storage before ONBOARDING_COMPANY_SIZE, causing the condition at OnboardingFlow.ts:155-160 to fire (since companySize is null while the path points to accounting), redirecting to Purpose and restarting the cycle.

    Problem 2 — Task Errors After Refresh

    prepareOnboardingOnyxData() in ReportUtils.ts:11884-11908 builds failure data that sets errors: 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, SequentialQueue retries 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, isInviteOnboardingComplete is set to true optimistically (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 the Onyx.set promise before calling Navigation.navigate. Since Onyx.set returns a promise, awaiting it ensures the guard sees updated values when navigation triggers. The onPress handlers should become async:

    onPress: async () => {
        await setOnboardingCompanySize(selectedCompanySize);
        Navigation.navigate(ROUTES.ONBOARDING_ACCOUNTING.getRoute(...));
    }
    

    This should be applied to all onboarding pages that call Onyx.set followed 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 revert isInviteOnboardingComplete to false so that getGuidedSetupDataForOpenReport can re-attempt the guided setup on subsequent openReport() 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:

    • Reading Onyx cache directly instead of connectWithoutView callbacks in the guard — this would get synchronously-updated values, but there's no clean public API for synchronous cache reads.
    • Skipping guard evaluation for intra-onboarding navigation — if both the current route and target route are onboarding screens, allow the navigation without checking getOnboardingInitialPath(). This is less precise but avoids the timing issue entirely.
    • Updating ONBOARDING_LAST_VISITED_PATH in 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 this to create a draft PR, @MelvinBot <your feedback> to refine this analysis, or explain why you are rejecting Melvin's proposal.

  3. added
    ExternalAdded to denote the issue can be worked on by a contributor
    on Mar 16, 2026
  4. added
    Help WantedApply this label when an issue is open to proposals by contributors
    on Mar 16, 2026
  5. melvin-bot commented on Mar 16, 2026

    @melvin-bot

    Triggered auto assignment to Contributor-plus team member for initial proposal review - @linhvovan29546 (External)

  6. melvin-bot commented on Mar 16, 2026

    @melvin-bot
  7. changed the title [-]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"[/+] on Mar 16, 2026
  8. shivang-goliyan commented on Mar 16, 2026

    @shivang-goliyan
    Contributor

    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 call Navigation.navigate(). The setter functions in Welcome/index.ts (lines 40-50) don't return the Onyx.set() promise.

    When OnboardingGuard.evaluate() runs during getStateForAction, it reads module-level variables populated by connectWithoutView callbacks (OnboardingGuard.ts:66-85). These callbacks haven't fired yet because Onyx flushes them asynchronously. So when getOnboardingInitialPath() checks currentOnboardingCompanySize at OnboardingFlow.ts:155-157, it's still null, 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, and BaseOnboardingAccounting.tsx:185-188.

    Problem 2 — Task Errors After Refresh:

    The failure data in prepareOnboardingOnyxData() (ReportUtils.ts:12079-12089) resets choice, createWorkspace, addExpenseApprovals, setupCategoriesAndTags, and setupTags — but omits isInviteOnboardingComplete: false. Since the optimistic data sets it to true at Report/index.ts:1269, a failed or interrupted OPEN_REPORT request leaves the flag permanently true, which blocks getGuidedSetupDataForOpenReport() 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, and BaseOnboardingAccounting.tsx, wrap the Navigation.navigate() calls in Navigation.setNavigationActionToMicrotaskQueue() after calling the Onyx setter. This defers navigation until Onyx callbacks have propagated. The codebase already uses this exact pattern in updateOnboardingValuesAndNavigation() at Welcome/index.ts:68-74, with the comment "We need to have the Onyx values updated before navigating back."

    For example in BaseOnboardingEmployees.tsx:

    setOnboardingCompanySize(selectedCompanySize);
    Navigation.setNavigationActionToMicrotaskQueue(() => {
        Navigation.navigate(ROUTES.ONBOARDING_ACCOUNTING.getRoute(route.params?.backTo));
    });

    Fix 2: Add isInviteOnboardingComplete: false to the NVP_INTRO_SELECTED failure data object at ReportUtils.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 async onPress handlers — this gives the strongest correctness guarantee but async event handlers in React Native can cause unhandled rejections if the component unmounts during the await. setNavigationActionToMicrotaskQueue is purpose-built for this timing problem and already proven in the codebase.

    I also looked at bypassing the guard for intra-onboarding NAVIGATE/PUSH actions, but commit 45a31bc9c59 explicitly reverted that approach (originally added in f5a4ecf0c1d), so the team has already considered and rejected it.

  9. 14 remaining items

  10. TMisiukiewicz commented on Apr 1, 2026

    @TMisiukiewicz
    Contributor

    Alright I was able to figure out the exact repro steps:

    1. Login with @gmail.com domain
    2. When in work email validation path, run the following code in the console:
    // Set the exact NVP_ONBOARDING state from the bug report
    window.Onyx.merge('nvp_onboarding', {
        hasCompletedGuidedSetupFlow: false,
        shouldValidate: true,
        signupQualifier: 'individual'
        // Note: isMergeAccountStepCompleted is intentionally absent
    });
    
    1. Refresh the page

    Looking for the root cause

  11. TMisiukiewicz commented on Apr 1, 2026

    @TMisiukiewicz
    Contributor

    @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

  12. linhvovan29546 commented on Apr 1, 2026

    @linhvovan29546
    Contributor

    @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.

  13. TMisiukiewicz commented on Apr 1, 2026

    @TMisiukiewicz
    Contributor

    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

  14. linhvovan29546 commented on Apr 1, 2026

    @linhvovan29546
    Contributor

    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
  15. TMisiukiewicz commented on Apr 2, 2026

    @TMisiukiewicz
    Contributor

    @linhvovan29546 everything looks good, so I think I can close my PR in favor of #86390 👍

  16. melvin-bot commented on Apr 24, 2026

    @melvin-bot

    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!

  17. dominictb commented on May 1, 2026

    @dominictb
    Contributor

    @linhvovan29546 Are you due payment here?

  18. linhvovan29546 commented on May 1, 2026

    @linhvovan29546
    Contributor

    @dominictb No, I haven’t reviewed PR yet, the issue was resolved elsewhere

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

BugSomething is broken. Auto assigns a BugZero manager.ExternalAdded to denote the issue can be worked on by a contributorHelp WantedApply this label when an issue is open to proposals by contributorsMonthlyKSv2ReviewingHas a PR in review

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions