[$250] Show descriptive error when work email with 2FA enabled is entered during onboarding

[MelvinBot]

Description

During onboarding, when a user enters a work email in the "Add work email" step that belongs to an Expensify account with Two-Factor Authentication (2FA) enabled, a generic "couldn't add email" error is shown. The backend returns a specific error message (<email> is a login for an Expensify account with Two-Factor Authentication (2FA) enabled), but the frontend does not surface this to the user.

Steps to Reproduce

1. Start the onboarding flow
2. Reach the "Add work email" step
3. Enter an email address that is already associated with an Expensify account that has 2FA enabled
4. Observe the error

Expected Behavior

The user should see a descriptive error message explaining that the email they entered is associated with an account that has 2FA enabled, so they understand it's a configuration issue on their end — not a system failure.

Actual Behavior

A generic "couldn't add email" error is displayed, leaving the user with the impression that something is broken on Expensify's side.

Additional Context

• The backend already returns the specific error: <email> is a login for an Expensify account with Two-Factor Authentication (2FA) enabled.
• The onboardingErrorMessage field contains this message, but the frontend likely needs to be updated to display it properly instead of falling back to a generic error.
• This is believed to be a frontend-only fix.

Issue Owner

Current Issue Owner: @mnshrm

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022036405801150652936
• Upwork Job ID: 2036405801150652936
• Last Price Increase: 2026-04-07

[MelvinBot]

Proposal

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

During onboarding, when a user enters a work email that belongs to an Expensify account with Two-Factor Authentication (2FA) enabled, a generic "Couldn't add work email" / "We couldn't add {email}. Please try again later…" error is shown. The backend returns a specific error explaining that the email has 2FA enabled, but the frontend never surfaces it.

What is the root cause of that problem?

There are two code paths where the specific backend error message is lost:

Path 1 — AddWorkEmail (initial email submission) in src/libs/actions/Session/index.ts (~line 1433–1481): This function uses API.write() (fire-and-forget), so it has no .then() handler to inspect the backend response. The failureData only sets isMergingAccountBlocked: true on NVP_ONBOARDING but never sets ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY. The backend's specific 2FA error message in response.message is entirely discarded.

Path 2 — MergeIntoAccountAndLogin (validation step) in src/libs/actions/Session/index.ts (~line 1543–1552): This function does use makeRequestWithSideEffects and inspects the response. However, the error branching at line 1544–1550 only handles one specific case: MERGE_ACCOUNT_INVALID_CODE_ERROR. For all other errors (including 2FA), the else branch at line 1549 sets only isMergingAccountBlocked: true and discards response.message.

On the UI side, OnboardingMergingAccountBlockedView (line 28–34) is already wired to display a specific error via onboardingErrorMessage — but since neither code path sets it for 2FA errors, the component always falls through to the generic subtitle.

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

1. Add a new translation key in src/languages/en.ts (and es.ts) for the 2FA-specific error, e.g. under onboarding.mergeBlockScreen:

   • Something like: twoFactorSubtitle: ({workEmail}) => \${workEmail} is associated with an Expensify account that has Two-Factor Authentication (2FA) enabled. Please disable 2FA on that account first, or use a different email.``

2. In AddWorkEmail (~line 1433): Change from API.write() to API.makeRequestWithSideEffects() so the response can be inspected. Add a .then() handler that checks response.message for the 2FA error string and, when matched, calls Onyx.merge(ONYXKEYS.ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, '<new translation key>').

3. In MergeIntoAccountAndLogin (~line 1548–1549): In the else branch, add a check for the 2FA error (similar to the existing MERGE_ACCOUNT_INVALID_CODE_ERROR check). When matched, set ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY to the new 2FA translation key instead of only setting isMergingAccountBlocked.

This ensures the OnboardingMergingAccountBlockedView component receives a specific error message for the 2FA case via its existing onboardingErrorMessage prop, and displays it instead of the generic fallback.

What alternative solutions did you explore? (Optional)

• Backend-only fix: Have the backend include onboardingErrorMessageTranslationKey in the onyxData of the AddWorkEmail response. This would work because the SaveResponseInOnyx middleware applies response.onyxData before failureData. However, this ties backend responses to frontend translation keys, which is fragile.
• Raw string approach: Change the ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY Onyx key type from TranslationPaths to string and store the backend's raw error message directly. This is simpler but breaks the translation pattern used everywhere else and would not support localization.

---

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 - @eh2077 (External)

[melvin-bot]

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

[gps949]

Proposal

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

When a user enters a work email with 2FA enabled during onboarding, a generic "Couldn't add work email / We couldn't add {email}. Please try again later…" message is displayed. The backend returns a specific error (<email> is a login for an Expensify account with Two-Factor Authentication (2FA) enabled), but the frontend discards it and shows only the generic fallback.

What is the root cause of that problem?

The root cause is in src/libs/actions/Session/index.ts in two places:

1. AddWorkEmail (line 1433): Uses API.write() with failureData that only sets isMergingAccountBlocked: true on NVP_ONBOARDING (line 1467). It never sets ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, so when the backend rejects the request due to 2FA, the UI shows OnboardingMergingAccountBlockedView with the generic mergeBlockScreen.subtitle fallback ("We couldn't add {email}. Please try again later…").

2. MergeIntoAccountAndLogin (line 1483): Uses makeRequestWithSideEffects and inspects the response at line 1544. The if branch checks for MERGE_ACCOUNT_INVALID_CODE_ERROR and correctly sets an error translation key. But the else branch (line 1549) catches all other errors — including 2FA — and only does Onyx.merge(ONYXKEYS.NVP_ONBOARDING, {isMergingAccountBlocked: true}) without setting ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY.

In both cases, the OnboardingMergingAccountBlockedView component (line 30-34) correctly checks for onboardingErrorMessage and would display it — but it's never populated for 2FA errors.

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

1. Add a 2FA-specific translation key in src/languages/en.ts (and es.ts) under onboarding.mergeBlockScreen:

mergeBlockScreen: {
    title: "Couldn't add work email",
    subtitle: (workEmail) => `We couldn't add ${workEmail}. Please try again later...`,
    twoFactorAuthSubtitle: (workEmail) => `${workEmail} is associated with an Expensify account that has Two-Factor Authentication (2FA) enabled. Please disable 2FA on that account or use a different work email.`,
},

2. In AddWorkEmail (line 1457-1470): Add a ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY entry in failureData so that when the backend returns a 2FA error, the error message key is set alongside isMergingAccountBlocked. Since API.write failureData fires on any non-success response, we need to detect whether it's a 2FA error. The cleanest approach: change the failureData to also set ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY to the 2FA translation key, and have the backend include a flag or check the response.message in the onyxData.

However, since API.write() doesn't give us response inspection, the simplest approach is: convert AddWorkEmail from API.write() to API.makeRequestWithSideEffects() (adding it to SIDE_EFFECT_REQUEST_COMMANDS in src/libs/API/types.ts), then add a .then() handler that checks response.message for the 2FA error string and conditionally sets the appropriate translation key:

// In AddWorkEmail, after changing to makeRequestWithSideEffects:
.then((response) => {
    if (response?.jsonCode === CONST.JSON_CODE.EXP_ERROR) {
        Onyx.merge(ONYXKEYS.NVP_ONBOARDING, {isMergingAccountBlocked: true});
        if (response?.message?.includes('Two-Factor Authentication')) {
            Onyx.merge(ONYXKEYS.ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, 
                'onboarding.mergeBlockScreen.twoFactorAuthSubtitle');
        }
    }
});

Remove the isMergingAccountBlocked: true from failureData since it's now handled in the .then().

3. In MergeIntoAccountAndLogin (line 1549): Add a 2FA check in the else branch:

} else if (response?.message?.includes('Two-Factor Authentication')) {
    Onyx.merge(ONYXKEYS.NVP_ONBOARDING, {isMergingAccountBlocked: true});
    Onyx.merge(ONYXKEYS.ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, 
        'onboarding.mergeBlockScreen.twoFactorAuthSubtitle');
} else {
    Onyx.merge(ONYXKEYS.NVP_ONBOARDING, {isMergingAccountBlocked: true});
}

This ensures the existing OnboardingMergingAccountBlockedView component (which already reads onboardingErrorMessage from Onyx and displays it via getErrorSubtitle()) will show the descriptive 2FA message instead of the generic fallback.

What alternative solutions did you explore? (Optional)

• Backend-only fix via onyxData: Have the backend include ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY in response.onyxData. This would work through the SaveResponseInOnyx middleware without needing to change API.write() to makeRequestWithSideEffects(). However, it couples backend responses to frontend translation keys.
• Generic passthrough of response.message: Store the raw backend message directly in Onyx instead of a translation key. This is simpler but breaks the translation/localization pattern used consistently throughout the app.

---

Timezone: UTC+8
Available hours: Flexible, generally available during business hours and evenings
Non-Expensify: @gps949

[mnshrm]

🚨 Edited by proposal-police: This proposal was edited at 2026-03-26 08:13:35 UTC.

Proposal

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

API error response is not taken into consideration, when user enters a work email with 2FA enabled, due to this a generic error text is shown to user which doesn't convey error to user.

Front-end should take into consideration onyxData field in error response, and display appropriate error message to user instead of generic message.

What is the root cause of that problem?

Root cause lies in ONYXKEYS.ts file, response received updates onboardingErrorMessage onyx key, but no such key is present in ONYXKEYS.ts .
Due to this error message is not merged in onyx data store, and since this doesn't exist it is not read by OnboardingMergingAccountBlockedView component.

OnboardingMergingAccountBlockedView component subscribes to ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, but this isn't the key returned by error response, so after response is returned, ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY is not updated, and it remains null, because of this, as per following code, app renders genericError message.

const [onboardingErrorMessage] = useOnyx(ONYXKEYS.ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY);
 const getErrorSubtitle = () => {
        if (onboardingErrorMessage) {
            return translate(onboardingErrorMessage);
        }
        // Fallback to generic error message
        return translate('onboarding.mergeBlockScreen.subtitle', workEmail);
    };

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

As per, Forms.md guide, there is no consensus, as to how server errors should be handled in Forms, and as of now it should be handled with FormAlerts without any inline error message. However, in my proposal I have kept inline error message as an extra option, which we can consider and implement with ease. We can discuss what should be the best option for work email flow.

Keeping this and the way BaseOnboardingWorkEmail and OnboardingMergingAccountBlockedView components work, we have 2 solutions

1. User is allowed 1 try to submit work email

• ONYXKEYS.ts : add onboardingErrorMessage key
• OnboardingMergingAccountBlockedView.tsx : We should subscribe to onboardingErrorMessage key, and add a condition in getErrorSubtitle method to check if value of this key is null or not, if it's null, it means error is not the one mentioned above in description, but if it's not null and has any value, we should render that value as error message, by returning its value.

2. User is allowed to change email after error

• ONYXKEYS.ts : add onboardingErrorMessage key
• BaseOnboardingWorkEmail: We should subscribe to onboardingErrorMessage key and add a check if the value is not null, we should call addErrorMessage method to add, onboardingErrorMessage value which will be " is a login for an Expensify account with Two-Factor Authentication (2FA) enabled." as inline error message. After user touches input again we should set value of this key as null.
• Welcome/index.ts: add an action to setOnboardingErrorMessage (One already exists as shown below but it updates ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY)

function setOnboardingErrorMessage(value: TranslationPaths | null) {
    Onyx.set(ONYXKEYS.ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, value);
}

If we implement this we can achieve expected results.

What alternative solutions did you explore? (Optional)

1. Using makeRequestWithSideEffects, as per doc this method should only be used after all options have been exhausted, since we can achieve our fix without it so I am not considering it as a good solution.
2. Backend + frontend fix: OnyxData field of response is trying to update onboardingErrorMessage key when no such key exists in codebase, instead it should update onbaordingErrorMessageTranslaitonPath key, which does exists and is handled correctly by OnboardingMergingAccountBlockedView.tsx, but if we use implement this solution, we need to add a new translation as well in frontend and make sure it translation path is the same in backend and response sent by it, which I can think is putting more efforts than required for a bug, which can be fixed by simple frontend fix as mentioned above.

[XiaoPengMei]

Proposal

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

During onboarding, when a user enters a work email that belongs to an Expensify account with 2FA enabled, the flow shows the generic merge-blocked message instead of the specific 2FA explanation returned by the backend.

What is the root cause of that problem?

The blocking screen is already capable of rendering a specific onboarding error message, but the onboarding session actions do not consistently preserve the backend's 2FA failure.

There are two places involved in src/libs/actions/Session/index.ts:

1. AddWorkEmail() uses API.write(...), so it never inspects the backend response at all. On failure it only sets isMergingAccountBlocked: true, which sends the user to the blocked screen with the generic subtitle.
2. MergeIntoAccountAndLogin() does inspect the response, but it only special-cases the invalid magic-code error. All other failures, including the 2FA merge error (401 Cannot merge accounts - 2FA enabled), fall through to the generic blocked state without setting a specific onboarding error key.

On the UI side, OnboardingMergingAccountBlockedView already reads ONYXKEYS.ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, so the missing part is preserving the 2FA error through these onboarding action paths.

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

I would keep the fix narrow and reuse the existing 2FA merge translation instead of adding a new parallel error system:

1. Add a tiny shared helper that maps onboarding merge responses to the right translation key:
   • Invalid validateCode -> contacts.genericFailureMessages.validateSecondaryLogin
   • 2FA enabled -> mergeAccountsPage.mergeFailure2FA.description
2. Change AddWorkEmail() from API.write(...) to API.makeRequestWithSideEffects(...) so we can inspect response.message/title and store the onboarding error key before setting isMergingAccountBlocked.
3. Update MergeIntoAccountAndLogin() to use the same helper, so 2FA failures also populate the onboarding error key instead of falling straight to the generic blocked message.
4. In OnboardingMergingAccountBlockedView, special-case the existing mergeAccountsPage.mergeFailure2FA.description key and pass workEmail into translate(...), since that translation already expects the email argument.

This keeps the fix frontend-only, avoids adding new locale strings, and makes both onboarding entry points behave consistently.

What alternative solutions did you explore? (Optional)

I considered adding a brand-new onboarding-specific 2FA translation under onboarding.mergeBlockScreen, but that would require duplicating existing 2FA copy across locales. Reusing the current merge-accounts 2FA description is smaller and keeps the message source-of-truth in one place.

[mnshrm]

Proposal

Updated

[mnshrm]

@eh2077, requesting proposal review