[$250] Required 2FA setup screen is unresponsive, blocking new-domain login and account merge

[m-natarajan]

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: v9.3.83-3
Reproducible in staging?: Needs Reproduction (Unable to reproduce with regular 2FA authentication)
Reproducible in production?: Needs Reproduction
If this was caught during regression testing, add the test name, ID and link from BrowserStack:
Email or phone of affected tester (no customers):
Logs: https://stackoverflow.com/c/expensify/questions/4856
Expensify/Expensify Issue URL:
Issue reported by: @Tmjarnesk1
Slack conversation (hyperlinked to channel name): #Expeisify Bugs

Action Performed:

1. User attempts to log in with new-domain email
2. User is routed to the onboarding page with the message “Two-factor authentication required.”
3. User selects “Enable two-factor authentication.”
4. Nothing happens; the button does not respond.
5. User tries clearing cache, using a different browser, and using a mobile device.
6. User remains blocked from completing 2FA setup and cannot access the new-domain account.
7. Because the user cannot access the new-domain account, they also cannot complete the required account merge after domain migration.

Expected Result:

User should be able to click “Enable two-factor authentication,” complete 2FA setup, log in with the new-domain account, and merge the old email/account via Settings > Account > Profile > Merge Accounts.

Actual Result:

The “Enable two-factor authentication” button is unresponsive. User cannot complete 2FA setup, cannot access the new-domain account, cannot merge accounts, and cannot forward receipts from the new-domain email.

Workaround:

Unknown

Additional Context:

• Domain migration was completed.
• Migration note stated that user already had an Expensify account using the new-domain email.
• User was instructed to log in with the new-domain email, then go to Settings > Account > Profile > Merge Accounts to merge the old email into the new account.
• Issue only occurs when logging in with the new-domain email.
• User can access the old-domain login.
• Domain settings require 2FA, so the user is correctly prompted for 2FA, but the setup flow is blocked.
• This does not appear to be a standard 2FA reset case unless the new-domain account is in a partially enabled/broken 2FA state.

Platforms:

Select the officially supported platforms where the issue was reproduced:

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

Screenshots/Videos

The screenshot with the console log is in Slack thread

View all open jobs on GitHub

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022060024083406042078
• Upwork Job ID: 2060024083406042078
• Last Price Increase: 2026-05-28

[MelvinBot]

Proposal

What is the root cause of that problem?

When a domain-migration user logs in and hasn't completed onboarding, the RequireTwoFactorAuthenticationOverlay renders on top of the onboarding screens. Pressing "Enable two-factor authentication" calls Navigation.navigate(getTwoFactorAuthRoute()), which builds a dynamic route via createDynamicRoute.

The navigation is silently blocked by the OnboardingGuard.shouldPreventReset. Here's how:

1. linkTo parses the dynamic route. When getActionFromState returns null for the generated path, it falls back to navigation.resetRoot(stateFromPath), dispatching a RESET action.
2. OnboardingGuard.shouldPreventReset sees the user is on an onboarding screen and the target is a non-onboarding screen (the 2FA setup page), so it blocks the RESET and sets an error message on the onboarding screen — which is hidden behind the overlay. The user sees nothing.
3. Since navigation never reaches the 2FA screen, isIn2FASetupFlow stays false, the overlay remains visible, and every subsequent tap is blocked the same way.

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

The OnboardingGuard.shouldPreventReset function should allow RESET actions that target 2FA setup screens. The fix should check whether the target focused route is a 2FA setup screen (using the existing isTwoFactorSetupScreen helper from Navigation.ts) and, if so, allow the reset instead of blocking it.

The change is in OnboardingGuard.ts:shouldPreventReset: before returning true to block the reset, add a check — if the target route is a 2FA setup screen, return false (allow it).

What alternative solutions did you explore? (Optional)

An alternative would be to modify the overlay's handleOnPress to bypass the normal Navigation.navigate path (e.g., using navigation.dispatch with a custom action that skips guards). However, this would be fragile and circumvent the guard system rather than fixing the actual conflict. Teaching the guard to recognize 2FA navigation as legitimate is cleaner and more maintainable.

Supporting evidence

Key files:

• RequireTwoFactorAuthenticationOverlay.tsx:55-57 — button handler
• useTwoFactorAuthRoute.ts:26-36 — route resolution (unvalidated accounts go to verify-account)
• OnboardingGuard.ts:117-132 — shouldPreventReset blocks non-onboarding targets
• linkTo/index.ts:158-163 — fallback to resetRoot when getActionFromState returns null

Data flow:

1. Server sets account.needsTwoFactorAuthSetup=true for domain-migration user
2. useShouldShowRequire2FAPage → overlay renders on top of onboarding
3. Button press → Navigation.navigate(dynamicRoute)
4. linkTo → getActionFromState returns null → resetRoot dispatched
5. OnboardingGuard.shouldPreventReset → blocked (onboarding → non-onboarding)
6. Error message sent to hidden onboarding screen → user sees nothing

Possibly related issue: #86194 covers a similar area (2FA + onboarding interaction) but focuses on showing a descriptive error rather than fixing the blocked navigation.

---

Next Steps for Contributor+ team:
To accept: @MelvinBot implement [this](https://github.com/Expensify/App/issues/91985#issuecomment-new) to create a draft PR.
To refine: @MelvinBot <your feedback>
To reject: Explain why you are rejecting Melvin's proposal.

[yusufdeveloper2903]

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

On a domain that enforces 2FA, a user logging in with the new-domain email lands on the full‑screen "Two-factor authentication required" gate, but tapping Enable two-factor authentication does nothing — the 2FA setup flow never opens, so the user can't complete setup, log in, or merge accounts. It is not reproducible with a "regular" already-onboarded 2FA account.

What is the root cause of that problem?

The required-2FA gate was rewritten in #90680 (merged 2026-05-25, three days before this report) as the full-screen RequireTwoFactorAuthenticationOverlay.

Its button handler computes the target route with no backTo argument:

https://github.com/Expensify/App/blob/d93353fd47faf/src/pages/RequireTwoFactorAuthenticationOverlay.tsx#L55-L57

const handleOnPress = () => {
    Navigation.navigate(getTwoFactorAuthRoute());
};

getTwoFactorAuthRoute() builds the 2FA target as a dynamic route for the not-yet-enabled cases:

https://github.com/Expensify/App/blob/d93353fd47faf/src/hooks/useTwoFactorAuthRoute.ts#L26-L36

if (!account?.validated) {
    return createDynamicRoute(DYNAMIC_ROUTES.TWO_FACTOR_AUTH_VERIFY_ACCOUNT.path, backTo);
}
return createDynamicRoute(DYNAMIC_ROUTES.TWO_FACTOR_AUTH_ROOT.path, backTo);

A dynamic route is a suffix appended to a base path. When backTo is undefined, createDynamicRoute falls back to Navigation.getActiveRoute() as that base:

https://github.com/Expensify/App/blob/d93353fd47faf/src/libs/Navigation/helpers/dynamicRoutesUtils/createDynamicRoute.ts#L62-L71

const routePath = basePath ?? Navigation.getActiveRoute();
return combinePathAndSuffix(routePath, dynamicRouteSuffixWithParams);

The overlay is rendered as an absolute-fill sibling on top of the whole RootStack, so the base is simply whatever screen happens to sit behind it:

https://github.com/Expensify/App/blob/d93353fd47faf/src/libs/Navigation/AppNavigator/AuthScreens.tsx#L378-L379

So the navigation target is <screen-behind-the-overlay>/two-factor-auth/verify-account. For a brand-new / just-migrated account being walked through onboarding, the screen behind the overlay is the onboarding flow (or a transitional, report-less Home), and that base does not host the dynamic 2FA suffix — getStateFromPath can't resolve <onboarding>/two-factor-auth/verify-account into a valid 2FA state, so Navigation.navigate no-ops and the press is logged but visibly "does nothing" (matching the console-log screenshot in Slack).

For a regular 2FA prompt (e.g. the still-used ConnectToXeroFlow, or an already-onboarded admin), the active route is a normal resolvable screen — settings/report — so the very same Navigation.navigate(getTwoFactorAuthRoute()) resolves and works. That is exactly why this is "Unable to reproduce with regular 2FA authentication": the bug is in the base the dynamic route is anchored to, which only goes wrong when the gate floats over the onboarding/empty-account context.

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

Anchor the 2FA dynamic route to a stable, always-resolvable base instead of the transient screen behind the overlay, by passing an explicit backTo to getTwoFactorAuthRoute.

In src/pages/RequireTwoFactorAuthenticationOverlay.tsx:

 const handleOnPress = () => {
-    Navigation.navigate(getTwoFactorAuthRoute());
+    Navigation.navigate(getTwoFactorAuthRoute(ROUTES.SETTINGS_SECURITY));
 };

(ROUTES.SETTINGS_SECURITY = settings/security, so the target becomes settings/security/two-factor-auth/verify-account — the screen 2FA naturally lives under, guaranteed to resolve regardless of what is behind the overlay, and giving the setup flow a sane return target.)

• File changed: src/pages/RequireTwoFactorAuthenticationOverlay.tsx only (add ROUTES import).
• No changes to useTwoFactorAuthRoute (its backTo param already exists and is used by ConnectToXeroFlow), the dynamic-route machinery, or the validated/requiresTwoFactorAuth branching — the regular/Xero path stays byte-for-byte identical.
• Works for both branches (verify-account for unvalidated accounts and two-factor-auth root for validated ones) since both go through the same createDynamicRoute(path, backTo).

Once navigation succeeds, the overlay auto-hides because the focused screen becomes a SET_UP_2FA_SCREENS member, so isIn2FASetupFlow flips true (existing logic, no change needed).

Test: Log in to a domain-enforced-2FA account that still needs setup while in the onboarding/new-account context, tap Enable two-factor authentication, and confirm the 2FA setup flow opens and can be completed.

What alternative solutions did you explore? (Optional)

• Capture a snapshot of Navigation.getActiveRoute() when the overlay first mounts and pass that as backTo. Rejected because the active route during onboarding is itself the broken base — snapshotting it doesn't make it a valid host for the 2FA suffix.
• Make the overlay a real navigated screen (push it as a route) instead of an absolute-fill sibling of RootStack.Navigator. Correct long-term, but a much larger navigation change for what is a one-line anchoring bug; out of scope for the regression fix.
• Special-case the parse failure inside getStateFromPath/createDynamicRoute to fall back to a default base. Rejected — it hides the real issue (the caller passing an unsuitable base) and risks masking other dynamic-route callers; fixing it at the call site is the surgical fix.

[dilshodmackbook-sketch]

Proposal

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

When a user is forced onto the "Two-factor authentication required" screen, clicking Enable two-factor authentication does nothing — the button is unresponsive and the user cannot complete 2FA setup, which blocks the new-domain login and account merge after domain migration.

What is the root cause of that problem?

The "Two-factor authentication required" screen is RequireTwoFactorAuthenticationOverlay. The button calls handleOnPress, which navigates to whatever getTwoFactorAuthRoute() returns:

https://github.com/Expensify/App/blob/main/src/pages/RequireTwoFactorAuthenticationOverlay.tsx#L55-L57

The overlay itself is a full-screen StyleSheet.absoluteFill that only un-mounts when shouldShowRequire2FAPage becomes false or the focused screen is in the 2FA setup flow:

https://github.com/Expensify/App/blob/main/src/pages/RequireTwoFactorAuthenticationOverlay.tsx#L59-L70

shouldShowRequire2FAPage is true under either of two conditions:

https://github.com/Expensify/App/blob/main/src/hooks/useShouldShowRequire2FAPage.ts#L10-L15

return (!!account?.needsTwoFactorAuthSetup && !account?.requiresTwoFactorAuth)
    || (!!account?.twoFactorAuthSetupInProgress && !hasCompletedGuidedSetupFlow);

So the overlay can be visible even when requiresTwoFactorAuth is true — via the second clause (twoFactorAuthSetupInProgress && !hasCompletedGuidedSetupFlow), which is exactly the "partially enabled / broken 2FA state" the bug description calls out for a new-domain account whose backend record says 2FA is required but the guided setup never completed.

Now look at useTwoFactorAuthRoute:

https://github.com/Expensify/App/blob/main/src/hooks/useTwoFactorAuthRoute.ts#L21-L39

const is2FAEnabled = !!account?.requiresTwoFactorAuth;
const getTwoFactorAuthRoute = (backTo?: Route): Route => {
    if (is2FAEnabled) {
        return ROUTES.SETTINGS_2FA_ENABLED;   // ← maps to SCREENS.TWO_FACTOR_AUTH.ENABLED
    }
    if (!account?.validated) {
        return createDynamicRoute(DYNAMIC_ROUTES.TWO_FACTOR_AUTH_VERIFY_ACCOUNT.path, backTo);
    }
    return createDynamicRoute(DYNAMIC_ROUTES.TWO_FACTOR_AUTH_ROOT.path, backTo);
};

When requiresTwoFactorAuth is true, the resolver returns SETTINGS_2FA_ENABLED → SCREENS.TWO_FACTOR_AUTH.ENABLED. But that screen is not in SET_UP_2FA_SCREENS, which is what gates the overlay-dismiss check:

https://github.com/Expensify/App/blob/main/src/libs/Navigation/Navigation.ts#L70-L79

So in the broken-state scenario the chain is:

1. twoFactorAuthSetupInProgress = true and requiresTwoFactorAuth = true → overlay shows.
2. User clicks the button → getTwoFactorAuthRoute() returns SETTINGS_2FA_ENABLED because is2FAEnabled = true.
3. Navigation does push to the "2FA Enabled" RHP screen, but because that screen isn't in SET_UP_2FA_SCREENS, isIn2FASetupFlow stays false and the absolute-fill overlay never un-mounts.
4. From the user's perspective the button is dead — navigation happened, but it's hidden under the overlay, with no path to the setup wizard.

It's not the underlying contradictory account state that breaks the button — the client-side flaw is that the overlay's own trigger condition admits a state where it routes to a screen that can't dismiss it.

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

When RequireTwoFactorAuthenticationOverlay is showing, the user — by the overlay's own definition — has not completed 2FA setup, so the requiresTwoFactorAuth shortcut in the resolver is the wrong branch for this caller. I'd let the resolver accept an explicit "I'm forcing setup" hint so the overlay's button always lands on a setup-flow screen that the overlay knows how to dismiss:

 type TwoFactorAuthRouteResult = {
-    getTwoFactorAuthRoute: (backTo?: Route) => Route;
+    getTwoFactorAuthRoute: (backTo?: Route, options?: {forceSetup?: boolean}) => Route;
     is2FAEnabled: boolean;
 };

 function useTwoFactorAuthRoute(): TwoFactorAuthRouteResult {
     const [account] = useOnyx(ONYXKEYS.ACCOUNT);
     const is2FAEnabled = !!account?.requiresTwoFactorAuth;

-    const getTwoFactorAuthRoute = (backTo?: Route): Route => {
-        if (is2FAEnabled) {
+    const getTwoFactorAuthRoute = (backTo?: Route, options?: {forceSetup?: boolean}): Route => {
+        // Callers that force the user into setup (e.g. the RequireTwoFactorAuthenticationOverlay)
+        // must bypass the "already enabled" shortcut — the account can be in a partial state where
+        // `requiresTwoFactorAuth` is true but setup never completed (twoFactorAuthSetupInProgress).
+        if (is2FAEnabled && !options?.forceSetup) {
             return ROUTES.SETTINGS_2FA_ENABLED;
         }
         if (!account?.validated) {
             return createDynamicRoute(DYNAMIC_ROUTES.TWO_FACTOR_AUTH_VERIFY_ACCOUNT.path, backTo);
         }
         return createDynamicRoute(DYNAMIC_ROUTES.TWO_FACTOR_AUTH_ROOT.path, backTo);
     };
     ...
 }

Then in RequireTwoFactorAuthenticationOverlay.tsx, pass the flag from the only caller that needs it:

- const handleOnPress = () => {
-     Navigation.navigate(getTwoFactorAuthRoute());
- };
+ const handleOnPress = () => {
+     Navigation.navigate(getTwoFactorAuthRoute(undefined, {forceSetup: true}));
+ };

This keeps the existing 3-way resolver behavior for the other call sites (SecuritySettingsPage, ConnectToXeroFlow, Enable2FACard, NonUSD/Finish) — they correctly want to land on the "enabled" page when 2FA is already on — and only the overlay opts into the unblocking behavior, where the destination is guaranteed to be in SET_UP_2FA_SCREENS so the overlay un-mounts.

What alternative solutions did you explore? (Optional)

1. Tighten is2FAEnabled to require completed setup, e.g. !!requiresTwoFactorAuth && !needsTwoFactorAuthSetup && !twoFactorAuthSetupInProgress. Fixes the overlay path but also reroutes SecuritySettingsPage and the Xero/bank flows for any user briefly in mid-setup, which is a behavior change well outside this bug. Rejected.
2. Add SCREENS.TWO_FACTOR_AUTH.ENABLED to SET_UP_2FA_SCREENS so the overlay dismisses when navigating to the enabled page. That makes the button feel responsive but lands the user on "2FA already enabled" while they've still failed to complete setup — wrong screen for the user's actual state. Rejected.
3. Trigger a RequireTwoFactorAuthenticationModal-style imperative open instead of Navigation.navigate. Bigger refactor for the same outcome and doesn't address the underlying mis-routing in the resolver. Rejected.
4. Directly call createDynamicRoute(...) inside handleOnPress without touching the hook. Works, but duplicates the account?.validated branching that already lives in useTwoFactorAuthRoute; the optional-flag approach keeps that logic in one place.

[KJ21-ENG]

🚨 Edited by proposal-police: This proposal was edited at 2026-05-28 15:52:22 UTC.

Proposal

What is the root cause of that problem?

This happens when the user is required to set up 2FA before they have completed NewDot onboarding.

The required-2FA overlay is global. Its button calls Navigation.navigate(getTwoFactorAuthRoute()), which should open the 2FA setup modal. However, the account is still in onboarding state because hasCompletedGuidedSetupFlow is false. OnboardingGuard allows navigation while the onboarding modal is currently focused, but as soon as the 2FA right modal is pushed, the focused root route is no longer onboarding. The guard then treats the user as trying to leave onboarding and redirects subsequent 2FA modal/nested navigation actions back to the onboarding route.

That puts the user back under the same required-2FA overlay, so the CTA looks unresponsive even though the initial button press did try to navigate.

There is also a smaller route-classification gap in the same area: isTwoFactorSetupScreen() only recognizes several 2FA leaf routes. It does not recognize the SCREENS.RIGHT_MODAL.TWO_FACTOR_AUTH parent route, and it misses the replacement-device 2FA leaf routes. That makes the overlay/side-panel checks fragile during intermediate 2FA modal states.

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

Update the onboarding navigation guard so required 2FA setup is an allowed exception to the onboarding lock.

Concretely:

• In src/libs/Navigation/guards/OnboardingGuard.ts, add a helper that detects whether the current action/state is entering or staying inside the 2FA setup modal stack.
• Only allow that exception when the account actually needs setup, e.g. account.needsTwoFactorAuthSetup or account.twoFactorAuthSetupInProgress is true and account.requiresTwoFactorAuth is still false.
• Keep redirecting all unrelated non-onboarding navigation while onboarding is incomplete.
• Keep shouldPreventReset protecting normal onboarding exits, but do not treat required 2FA setup as an onboarding escape hatch.

Also harden the overlay classifier in src/libs/Navigation/Navigation.ts by including SCREENS.RIGHT_MODAL.TWO_FACTOR_AUTH, SCREENS.TWO_FACTOR_AUTH.REPLACE_VERIFY_OLD, and SCREENS.TWO_FACTOR_AUTH.REPLACE_VERIFY_NEW in the 2FA route allowlist.

Add focused tests:

• OnboardingGuard should allow navigation/nested actions for the 2FA modal when onboarding is incomplete and the account needs 2FA setup.
• The same guard should still redirect unrelated non-onboarding navigation in that state.
• isTwoFactorSetupScreen() should return true for the 2FA modal parent and every 2FA leaf route.

This keeps the fix frontend-only. It does not change the 2FA APIs, domain 2FA policy behavior, account merge behavior, or the normal onboarding completion rules.

What alternative solutions did you explore? (Optional)

Only expanding SET_UP_2FA_SCREENS would make the overlay hide for more 2FA routes, but it would not stop OnboardingGuard from redirecting the modal flow back to onboarding after the first navigation. Hiding the overlay with local click state would also be too narrow because direct links and restored navigation state would still hit the guard.

[melvin-bot]

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

[wildan-m]

🚫 Duplicated proposal withdrawn by 🤖 ProposalPolice.

[melvin-bot]

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

[github-actions]

⚠️ @KJ21-ENG Your proposal is a duplicate of an already existing proposal and has been automatically withdrawn to prevent spam. Please review the existing proposals before submitting a new one.