You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Due for payment 2026-06-01] [$250] Show descriptive error when work email with 2FA enabled is entered during onboarding #86194
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
Start the onboarding flow
Reach the "Add work email" step
Enter an email address that is already associated with an Expensify account that has 2FA enabled
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.
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 setsONBOARDING_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?
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.``
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>').
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.
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
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:
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…").
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.writefailureData 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:
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
🚨 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.
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
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.
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)
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.
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.
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:
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.
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:
Add a tiny shared helper that maps onboarding merge responses to the right translation key:
Change AddWorkEmail() from API.write(...) to API.makeRequestWithSideEffects(...) so we can inspect response.message/title and store the onboarding error key before setting isMergingAccountBlocked.
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.
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.
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
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.
[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.
Activity
MelvinBot commentedon Mar 24, 2026
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) insrc/libs/actions/Session/index.ts(~line 1433–1481): This function usesAPI.write()(fire-and-forget), so it has no.then()handler to inspect the backend response. ThefailureDataonly setsisMergingAccountBlocked: trueonNVP_ONBOARDINGbut never setsONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY. The backend's specific 2FA error message inresponse.messageis entirely discarded.Path 2 —
MergeIntoAccountAndLogin(validation step) insrc/libs/actions/Session/index.ts(~line 1543–1552): This function does usemakeRequestWithSideEffectsand 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), theelsebranch at line 1549 sets onlyisMergingAccountBlocked: trueand discardsresponse.message.On the UI side,
OnboardingMergingAccountBlockedView(line 28–34) is already wired to display a specific error viaonboardingErrorMessage— 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?
Add a new translation key in
src/languages/en.ts(andes.ts) for the 2FA-specific error, e.g. underonboarding.mergeBlockScreen: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.``In
AddWorkEmail(~line 1433): Change fromAPI.write()toAPI.makeRequestWithSideEffects()so the response can be inspected. Add a.then()handler that checksresponse.messagefor the 2FA error string and, when matched, callsOnyx.merge(ONYXKEYS.ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, '<new translation key>').In
MergeIntoAccountAndLogin(~line 1548–1549): In theelsebranch, add a check for the 2FA error (similar to the existingMERGE_ACCOUNT_INVALID_CODE_ERRORcheck). When matched, setONBOARDING_ERROR_MESSAGE_TRANSLATION_KEYto the new 2FA translation key instead of only settingisMergingAccountBlocked.This ensures the
OnboardingMergingAccountBlockedViewcomponent receives a specific error message for the 2FA case via its existingonboardingErrorMessageprop, and displays it instead of the generic fallback.What alternative solutions did you explore? (Optional)
onboardingErrorMessageTranslationKeyin theonyxDataof theAddWorkEmailresponse. This would work because theSaveResponseInOnyxmiddleware appliesresponse.onyxDatabeforefailureData. However, this ties backend responses to frontend translation keys, which is fragile.ONBOARDING_ERROR_MESSAGE_TRANSLATION_KEYOnyx key type fromTranslationPathstostringand 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 thisto create a draft PR,@MelvinBot <your feedback>to refine this analysis, or explain why you are rejecting Melvin's proposal.melvin-bot commentedon Mar 24, 2026
Triggered auto assignment to Contributor-plus team member for initial proposal review - @eh2077 (
External)[-]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[/+]melvin-bot commentedon Mar 24, 2026
Job added to Upwork: https://www.upwork.com/jobs/~022036405801150652936
gps949 commentedon Mar 24, 2026
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.tsin two places:AddWorkEmail(line 1433): UsesAPI.write()withfailureDatathat only setsisMergingAccountBlocked: trueonNVP_ONBOARDING(line 1467). It never setsONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY, so when the backend rejects the request due to 2FA, the UI showsOnboardingMergingAccountBlockedViewwith the genericmergeBlockScreen.subtitlefallback ("We couldn't add {email}. Please try again later…").MergeIntoAccountAndLogin(line 1483): UsesmakeRequestWithSideEffectsand inspects the response at line 1544. Theifbranch checks forMERGE_ACCOUNT_INVALID_CODE_ERRORand correctly sets an error translation key. But theelsebranch (line 1549) catches all other errors — including 2FA — and only doesOnyx.merge(ONYXKEYS.NVP_ONBOARDING, {isMergingAccountBlocked: true})without settingONBOARDING_ERROR_MESSAGE_TRANSLATION_KEY.In both cases, the
OnboardingMergingAccountBlockedViewcomponent (line 30-34) correctly checks foronboardingErrorMessageand 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(andes.ts) underonboarding.mergeBlockScreen:2. In
AddWorkEmail(line 1457-1470): Add aONBOARDING_ERROR_MESSAGE_TRANSLATION_KEYentry infailureDataso that when the backend returns a 2FA error, the error message key is set alongsideisMergingAccountBlocked. SinceAPI.writefailureDatafires on any non-success response, we need to detect whether it's a 2FA error. The cleanest approach: change thefailureDatato also setONBOARDING_ERROR_MESSAGE_TRANSLATION_KEYto the 2FA translation key, and have the backend include a flag or check theresponse.messagein theonyxData.However, since
API.write()doesn't give us response inspection, the simplest approach is: convertAddWorkEmailfromAPI.write()toAPI.makeRequestWithSideEffects()(adding it toSIDE_EFFECT_REQUEST_COMMANDSinsrc/libs/API/types.ts), then add a.then()handler that checksresponse.messagefor the 2FA error string and conditionally sets the appropriate translation key:Remove the
isMergingAccountBlocked: truefromfailureDatasince it's now handled in the.then().3. In
MergeIntoAccountAndLogin(line 1549): Add a 2FA check in theelsebranch:This ensures the existing
OnboardingMergingAccountBlockedViewcomponent (which already readsonboardingErrorMessagefrom Onyx and displays it viagetErrorSubtitle()) will show the descriptive 2FA message instead of the generic fallback.What alternative solutions did you explore? (Optional)
onyxData: Have the backend includeONBOARDING_ERROR_MESSAGE_TRANSLATION_KEYinresponse.onyxData. This would work through theSaveResponseInOnyxmiddleware without needing to changeAPI.write()tomakeRequestWithSideEffects(). However, it couples backend responses to frontend translation keys.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 commentedon Mar 24, 2026
🚨 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.
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
If we implement this we can achieve expected results.
What alternative solutions did you explore? (Optional)
warwickmei commentedon Mar 26, 2026
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:AddWorkEmail()usesAPI.write(...), so it never inspects the backend response at all. On failure it only setsisMergingAccountBlocked: true, which sends the user to the blocked screen with the generic subtitle.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,
OnboardingMergingAccountBlockedViewalready readsONYXKEYS.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:
Invalid validateCode->contacts.genericFailureMessages.validateSecondaryLogin2FA enabled->mergeAccountsPage.mergeFailure2FA.descriptionAddWorkEmail()fromAPI.write(...)toAPI.makeRequestWithSideEffects(...)so we can inspectresponse.message/titleand store the onboarding error key before settingisMergingAccountBlocked.MergeIntoAccountAndLogin()to use the same helper, so 2FA failures also populate the onboarding error key instead of falling straight to the generic blocked message.OnboardingMergingAccountBlockedView, special-case the existingmergeAccountsPage.mergeFailure2FA.descriptionkey and passworkEmailintotranslate(...), 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 commentedon Mar 26, 2026
Proposal
Updated
mnshrm commentedon Mar 26, 2026
@eh2077, requesting proposal review
76 remaining items
mallenexpensify commentedon Jun 2, 2026
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
@eh2077 plz complete the BZ checklist and tag me in a post once you have. Thx
mnshrm commentedon Jun 2, 2026
Contributor details
Your Expensify account email: asysnsrs665@gmail.com
Upwork Profile Link: https://www.upwork.com/freelancers/~01dd0bcc8a7e29b961
melvin-bot commentedon Jun 2, 2026
✅ Contributor details stored successfully. Thank you for contributing to Expensify!
mnshrm commentedon Jun 2, 2026
@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
dylanexpensify commentedon Jun 2, 2026
@MelvinBot did you create this issue from a slack thread?
MelvinBot commentedon Jun 2, 2026
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.mallenexpensify commentedon Jun 2, 2026
@mnshrm plz try again
https://www.upwork.com/jobs/~022061599868933665224
(I think I messed something up).
mnshrm commentedon Jun 3, 2026
@mallenexpensify, applied for the job
mallenexpensify commentedon Jun 3, 2026
@mnshrm can you please accept the job below? Please reply here and tag me once you have.
https://www.upwork.com/jobs/~022061599868933665224
mnshrm commentedon Jun 4, 2026
@mallenexpensify, I have acceptrd the offer for the same.
https://www.upwork.com/jobs/~022061599868933665224
eh2077 commentedon Jun 4, 2026
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:
Test:
Do we agree 👍 or 👎
Zapier Logs
Run ID: 00040eee-20b9-a213-af5e-7b930c15d594eh2077 commentedon Jun 4, 2026
@mallenexpensify sorry for the delay. checklist done!
mallenexpensify commentedon Jun 5, 2026
@mnshrm paid, summary updated above. Thx.
^ Test case created. Thx
Thx
laurenreidexpensify commentedon Aug 4, 2026
$250 approved @eh2077