Skip to content

[Due for payment 2026-06-01] [$250] Show descriptive error when work email with 2FA enabled is entered during onboarding #86194

Closed

Description

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

Created from this slack thread

Issue OwnerCurrent Issue Owner: @mallenexpensify
Upwork Automation - Do Not Edit
  • Upwork Job URL: https://www.upwork.com/jobs/~022036405801150652936
  • Upwork Job ID: 2036405801150652936
  • Last Price Increase: 2026-04-07

Activity

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

    @MelvinBot
    ContributorAuthor

    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.

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

    @melvin-bot

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

  6. changed the title [-]Show descriptive error when work email with 2FA enabled is entered during onboarding[/-] [+][$250] Show descriptive error when work email with 2FA enabled is entered during onboarding[/+] on Mar 24, 2026
  7. melvin-bot commented on Mar 24, 2026

    @melvin-bot
  8. gps949 commented on Mar 24, 2026

    @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

  9. mnshrm commented on Mar 24, 2026

    @mnshrm
    Contributor

    🚨 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.
    1. 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.
  10. warwickmei commented on Mar 26, 2026

    @warwickmei

    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.

  11. mnshrm commented on Mar 26, 2026

    @mnshrm
    Contributor

    Proposal

    Updated

  12. mnshrm commented on Mar 26, 2026

    @mnshrm
    Contributor

    @eh2077, requesting proposal review

  13. 76 remaining items

  14. mallenexpensify commented on Jun 2, 2026

    @mallenexpensify
    Contributor

    Payment Summary

    Contributor: @mnshrm paid $250 via Upwork
    Contributor+: @eh2077 due $250 via NewDot

    @mnshrm can you please accept the job below? Please reply here and tag me once you have.
    If you're not sent an offer in Upwork when you're assigned to an issue, please tag me. If an Upwork job exists, please submit a proposal.
    https://www.upwork.com/jobs/~022061599868933665224

    @mnshrm in a dedicated post, can you enter your Upwork details? I'm hoping they'll be saved to send you auto-offers in the future. Thx

    Contributor details
    Your Expensify account email: email@email.com
    Upwork Profile Link: upwork.com/freelancers/~xxxxx

    @eh2077 plz complete the BZ checklist and tag me in a post once you have. Thx

  15. mnshrm commented on Jun 2, 2026

    @mnshrm
    Contributor

    Contributor details
    Your Expensify account email: asysnsrs665@gmail.com
    Upwork Profile Link: https://www.upwork.com/freelancers/~01dd0bcc8a7e29b961

  16. melvin-bot commented on Jun 2, 2026

    @melvin-bot

    ✅ Contributor details stored successfully. Thank you for contributing to Expensify!

  17. mnshrm commented on Jun 2, 2026

    @mnshrm
    Contributor

    @mallenexpensify, this link is giving me access denied error, citing job as private.
    https://www.upwork.com/jobs/~022061599868933665224.

    Btw, I had submitted a proposal on this link when issue was assigned.
    https://www.upwork.com/jobs/~022036405801150652936

  18. dylanexpensify commented on Jun 2, 2026

    @dylanexpensify
    Contributor

    @MelvinBot did you create this issue from a slack thread?

  19. MelvinBot commented on Jun 2, 2026

    @MelvinBot
    ContributorAuthor

    I don't have memory of past sessions, so I can only go by what's recorded on this issue. This issue was authored by MelvinBot, but the body has no Slack thread: link — that's the marker I add to the issue body whenever I file something from a Slack thread.

    Based on that, there's no record that this one originated from a Slack thread. If it had, you'd see a **Slack thread:** <url> line in the description.

  20. mallenexpensify commented on Jun 2, 2026

    @mallenexpensify
    Contributor

    @mnshrm plz try again
    https://www.upwork.com/jobs/~022061599868933665224
    (I think I messed something up).

  21. mnshrm commented on Jun 3, 2026

    @mnshrm
    Contributor

    @mallenexpensify, applied for the job

  22. mallenexpensify commented on Jun 3, 2026

    @mallenexpensify
    Contributor

    @mnshrm can you please accept the job below? Please reply here and tag me once you have.
    https://www.upwork.com/jobs/~022061599868933665224

  23. mnshrm commented on Jun 4, 2026

    @mnshrm
    Contributor
  24. eh2077 commented on Jun 4, 2026

    @eh2077
    Contributor

    BugZero Checklist:

    • [Contributor] The offending PR and associated issue have been commented on, pointing out the bug it caused and why, so the author and reviewers can learn from the mistake.

      Link to the comment on the PR: NA. I can't find a PR that caused this issue. It should be a polish of an edge case.
      Link to the comment on the Issue: NA.

    • [Contributor] If the regression was CRITICAL (e.g. interrupts a core flow) A discussion in #expensify-open-source has been started about whether any other steps should be taken (e.g. updating the PR review checklist) in order to catch this type of bug sooner.

      Link to discussion: NA

    • [Contributor] If it was decided to create a regression test for the bug, please propose the regression test steps using the template below to ensure the same bug will not reach production again.

    • [BugZero Assignee] Create a GH issue for creating/updating the regression test once above steps have been agreed upon.

      Link to issue: https://github.com/Expensify/Expensify/issues/645600

    Regression Test Proposal

    Precondition:

    • A account with work email and 2FA enabled.

    Test:

    1. Navigate to new expensify
    2. Enter a new email id, and click on continue button.
    3. Click on join button
    4. Wait for new onboarding flow popup.
    5. On 'what's your work email' popup, enter a work email already associated with an account with 2FA enabled.
    6. Click on add work email button.
    7. Error should be displayed with message ' is a login for an Expensify account with Two-Factor Authentication (2FA) enabled.'
    8. user attempts to correct mistake, by modifying work email input.
    9. Error should be removed and not be displayed as soon as input value changes.
    10. User enters a new work email not associated to any account
    11. User clicks on add work email button
    12. User enters OTP received on work email
    13. User gets success message on submitting correct OTP

    Do we agree 👍 or 👎

    Zapier Logs Run ID: 00040eee-20b9-a213-af5e-7b930c15d594
  25. eh2077 commented on Jun 4, 2026

    @eh2077
    Contributor

    @mallenexpensify sorry for the delay. checklist done!

  26. mallenexpensify commented on Jun 5, 2026

    @mallenexpensify
    Contributor

    @mnshrm paid, summary updated above. Thx.

    ^ Test case created. Thx

    Thx

  27. laurenreidexpensify commented on Aug 4, 2026

    @laurenreidexpensify
    Contributor

    $250 approved @eh2077

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

Metadata

Metadata

Labels

Awaiting PaymentAuto-added when associated PR is deployed to productionBugSomething is broken. Auto assigns a BugZero manager.DailyKSv2ExternalAdded to denote the issue can be worked on by a contributor

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions