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

[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

• src/libs/actions/Welcome/OnboardingFlow.ts - getOnboardingInitialPath() redirect logic
• src/libs/Navigation/guards/OnboardingGuard.ts - Guard that triggers redirects
• src/libs/Navigation/NavigationRoot.tsx - Updates ONBOARDING_LAST_VISITED_PATH
• src/pages/OnboardingAccounting/BaseOnboardingAccounting.tsx - Accounting step (where loop was observed)
• src/libs/ReportUtils.ts - prepareOnboardingOnyxData() failure handling
• src/libs/actions/Report/index.ts - getGuidedSetupDataForOpenReport()

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 Owner

Current 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

[MelvinBot]

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.

[melvin-bot]

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

[melvin-bot]

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

[shivang-goliyan]

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.