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-30] [$250] “Upload Additional Documents” Page Appears with No Required Documents #90505
Version Number: Reproducible in staging?: Needs Reproduction 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:@rafecolton Slack conversation (hyperlinked to channel name): #Expensify Product
Action Performed:
Initiate Add bank account flow from Workflows
Fill out the Corpay form
Select: UK as the bank account country, UK as the citizenship country
Use a US address
Continue through the flow until reaching the Upload Additional Documents page
Expected Result:
If no documents are required:
The page should not be shown
OR
If the page is shown:
Required upload fields should be displayed
Actual Result:
Upload Additional Documents” page appears:
With no required fields
No upload requirements displayed
User can skip the page without providing any data
Workaround:
Unknown
Platforms:
Select the officially supported platforms where the issue was reproduced:
The country is derived from the workspace currency via mapCurrencyToCountry, NOT from the bank account country. For a USD workspace adding a UK bank account:
getNeededDocumentsStatusForSignerInfo('USD', 'US') → all flags false → empty page
2. NonUSD/SignerInfo flow (secondary bug) — SignerDetailsFormPages.tsx:24-31: The UPLOAD_DOCUMENTS page is never conditionally skipped, unlike the beneficial owner flow which skips DOCUMENTS for GB+GB. If any edge case causes country to be empty in the draft, the page renders with no fields and no skip.
Solution
Fix 1 (EnterSignerInfo): In EnterSignerInfo/subSteps/UploadDocuments.tsx, read the bank account country from the reimbursement account data instead of deriving it from the workspace currency:
This mirrors how getCurrencyForNonUSDBankAccount reads country (from the draft/achData first, falling back to currency mapping).
Fix 2 (skip logic): In SignerDetailsFormPages.tsx, add UPLOAD_DOCUMENTS to skipPages when all document flags from getNeededDocumentsStatusForSignerInfo are false. This provides a safety net: if no documents are needed, the page is skipped entirely rather than shown empty.
Similarly, add skip logic in EnterSignerInfo/index.tsxbodyContent to conditionally exclude UploadDocuments.
Investigation details
How getNeededDocumentsStatusForSignerInfo evaluates for the reported scenario (USD workspace + UK bank account):
Flag
Condition
USD + US (buggy)
USD + GB (correct)
isCopyOfIDNeeded
EUR/GBP currency or AU country
false
false
isAddressProofNeeded
EUR currency or GB/AU country
false
true
isProofOfDirectorsNeeded
CA/AU country
false
false
isCodiceFiscaleNeeded
IT country
false
false
isPRDAndFSGNeeded
AU country
false
false
With the correct country (GB), at least isAddressProofNeeded would be true, showing the address proof upload field.
Related issue:#90494 ("Frontend Uses Wrong Country Field to Determine Proof of Address Requirement") describes the same root cause from a different angle — proof of address isn't prompted because the wrong country is used in the determination logic.
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.
BeneficialOwnerDetailsFormPages decides whether to skip the Documents sub-page with a single hand-rolled rule that only covers one specific scenario — bank country = GB AND nationality = GB:
The Documents sub-page itself unconditionally renders its three header strings ("Upload additional documentation", "Please upload…", "Accepted files…") and only gates the upload fields on the per-document flags — so if getNeededDocumentsStatusForBeneficialOwner returns every flag false, the user sees a page with three labels, no inputs, and a working submit button:
So there are two sources of truth for "are documents needed?" that don't agree:
Skip rule (in the orchestrator) — pattern-matches one case.
Doc-needed flags (in getNeededDocumentsStatusForBeneficialOwner) — the actual per-document rules.
Whenever the rules agree that nothing is required but the skip rule misses the case, the user reaches an empty page. That's what's happening in the repro: with the orchestrator currently consulting only nationality and countryStepCountryValue (no address country), the all-false output for UK/UK/US slips through, and even editing back into the page from Confirmation.tsx#L90 lands here.
This issue is downstream of #90494 — proof of address should be required for UK/UK/US — but the empty-page failure mode is a separate UX bug: the orchestrator doesn't trust the rules helper.
What changes do you think we should make in order to solve the problem?
Make getNeededDocumentsStatusForBeneficialOwner the single source of truth. Two coordinated changes:
1. Derive skipPages from the rules helper in BeneficialOwnerDetailsFormPages.tsx:
The fourth beneficialOwnerAddressCountry argument matches the signature change proposed in #90494 — even if that PR ships first or later, the orchestrator gets correct skip behaviour as soon as the helper knows about the address country.
2. Defense in depth — auto-advance from Documents.tsx when no document is required, so deep links (e.g. editing into the page from Confirmation) don't strand the user on an empty page:
The orchestrator change is the real fix; the Documents.tsx guard is a safety net for any direct navigation. Together they make "page renders ↔ at least one document is needed" an invariant enforced by the rules helper, not by parallel hardcoded conditions.
What alternative solutions did you explore?
I considered keeping the orchestrator's hardcoded skip rule and just adding the useEffect-based auto-advance inside Documents.tsx. That would make the empty page un-reachable but would leave two parallel rule sources around, which is exactly the trap the current code fell into. Centralizing skip on the helper means future tweaks to "which docs are needed?" automatically propagate to "is the page shown?" without anyone remembering to update two files.
I also considered rendering an explicit empty-state ("No documents required, continue") instead of skipping. It's a valid pattern, but for the bank account flow the page exists only to collect uploads — there's nothing for a user to read or confirm here — so showing it adds a click without value. Skip is the right call.
The Documents sub-step in the NonUSD beneficial-owner flow is gated by a narrow hardcoded special case that doesn't match the predicate that drives what's rendered inside the page, so the page can mount with all four content sections collapsed to false.
1. Skip rule and render rule are out of sync.
The page lists are computed in BeneficialOwnerDetailsFormPages.tsx:
skipPages only adds DOCUMENTS when the bank country in the draft is exactly GB and the owner's nationality is exactly GB. Meanwhile, what the Documents page actually renders is gated on getNeededDocumentsStatusForBeneficialOwner(currency, country, beneficialOwnerNationality):
isCodiceFiscaleNeeded: accountCountry === IT → false
The Documents component renders only those four sections (Documents.tsx L116‑L223), so the visible content is just the heading and two supporting paragraphs, and useReimbursementAccountStepFormSubmit happily lets the user submit because all fields are optional.
2. Where the special case actually fails.
The intent on BeneficialOwnerDetailsFormPages.tsx:84 is to catch this exact scenario, but it reads the bank country only from reimbursementAccountDraft:
The Documents page reads the same country via getCurrencyForNonUSDBankAccount, which falls back to reimbursementAccount.achData.country when the draft is empty:
So when the user enters the flow with country only in achData (e.g. after a server-side hydration of the existing reimbursement account), countryStepCountryValue resolves to '', the GB && GB clause is false, DOCUMENTS is not skipped, and the empty page renders even though getNeededDocumentsStatusForBeneficialOwner — which uses the fallback — produces all-false flags.
What changes do you think we should make in order to solve the problem?
I'd derive the skip predicate from the same function that drives the page's render, instead of duplicating a narrow shape of it in the parent. That way, "page is empty" and "page is skipped" can't drift apart.
This removes the GB‑GB hardcode, uses the achData‑aware country read so the predicate fires even when the draft is empty, and skips DOCUMENTS for any current/future combination where all four flags collapse to false (e.g. the GBP/UK/UK case from this report, and also whatever new flag rule lands when #90494 is fixed).
useSubPage already routes around skipped pages on both nextPage and prevPage (useSubPage/index.tsx L47‑L72), so the existing back-button handler (L103‑L125) continues to work unchanged.
What alternative solutions did you explore? (Optional)
Auto-advance from inside Documents.tsx with a useEffect that calls onNext() when all four flags are false. It's a smaller diff and covers the case where a user lands on the page via a direct URL (which skipPages doesn't block, since useSubPage only filters in nextPage/prevPage). I'd avoid it as the primary fix though — it causes a visible flash of the empty page on mount and forces the next page's mount into a render cycle of the page being skipped. A complementary, smaller hardening if direct-URL navigation is a concern in practice, layered on top of the skipPages fix above.
🚨 Edited by proposal-police: This proposal was edited at 2026-05-13 13:45:01 UTC.
Replaces my earlier proposal. The prior body scoped this to the signer/director upload step, but the screenshot shows the Owner info panel and owner-specific copy. The verified failing path is the beneficial-owner Documents subpage, so the root cause and scope are updated to that flow.
Proposal
Please re-state the problem that we are trying to solve in this issue.
The non-USD bank-account flow can show the beneficial-owner "Upload additional documentation" page with only the heading/copy and no upload controls. In the reported UK bank account / UK citizenship / US address case, the user reaches an owner-info upload step that either should request proof of address or should be skipped when no documents are required.
What is the root cause of that problem?
The screenshot is the beneficial-owner flow: BeneficialOwnerDetailsFormPages renders the Owner info step and includes the DOCUMENTS subpage in the owner page list:
That parent page decides whether to skip DOCUMENTS with a separate hardcoded predicate based only on bank country from the draft and owner nationality:
But the document page itself uses getCurrencyForNonUSDBankAccount(...) and getNeededDocumentsStatusForBeneficialOwner(...) to decide which upload controls to render:
The helper never receives the beneficial owner's residential address country. For the reported state (currency = GBP, bank country GB, nationality GB, address country US), the existing helper returns all document flags false because it only checks currency, bank country, and nationality:
So two sources of truth drift apart: the parent decides page visibility with a narrow draft-only GB/GB rule, while the child decides visible uploads with a helper that ignores the owner's address country. That combination allows the owner documents page to mount with no required controls.
What changes do you think we should make in order to solve the problem?
Add the beneficial owner's residential address country to the document-requirement contract. In getNeededDocumentsStatusForBeneficialOwner, accept a fourth beneficialOwnerAddressCountry argument and make isProofOfAddressNeeded true when both countries are known and the owner address country differs from the bank account country. The address field already exists as BENEFICIAL_OWNER_DATA.COUNTRY:
Then update the two current beneficial-owner callers:
In BeneficialOwnerDetailsFormSubSteps/Documents.tsx, read ${PREFIX}_${ownerBeingModifiedID}_${COUNTRY} from the reimbursement account draft and pass it with currency, bank country, and nationality. This makes the reported UK bank / UK nationality / US address case render the proof-of-address upload instead of an empty page.
In BeneficialOwnerDetailsFormSubSteps/Confirmation.tsx, pass the same owner address country into the helper so the confirmation summary and edit links use the same document flags as the upload page:
Finally, in BeneficialOwnerDetailsFormPages.tsx, replace the hardcoded countryStepCountryValue === GB && beneficialOwnerNationality === GB skip with the same helper result. Subscribe to ONYXKEYS.REIMBURSEMENT_ACCOUNT and the policy, use getCurrencyForNonUSDBankAccount(...) for the bank country/currency source, read the owner address country from the draft, then skip SUB_PAGE_NAMES.DOCUMENTS only when all four helper flags are false. That keeps the page-list decision aligned with the fields actually rendered by Documents.
Scope boundaries:
Files touched: src/pages/ReimbursementAccount/NonUSD/utils/getNeededDocumentsStatusForBeneficialOwner.ts - helper signature and isProofOfAddressNeeded; src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Documents.tsx - owner address country read and helper call; src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Confirmation.tsx - helper call for document summary rows; src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx - skipPages calculation.
Platforms: all platforms using the shared non-USD reimbursement account flow.
Code paths / callers explicitly NOT touched: signer/director upload pages, USD reimbursement account flow, wallet international deposit account flow, and backend Corpay document rules.
API contracts or backend behavior changes: no.
What alternative solutions did you explore? (Optional)
MelvinBot pointed at EnterSignerInfo/signer upload logic, but the attached media shows the owner-info panel and the owner-specific "direct or indirect owner of 25% or more" copy, so the signer page is not the failing page in this issue. The signer helper also already forces address proof for a GB bank account, which does not explain the empty owner page shown here.
Human proposals that derive the parent skip from the beneficial-owner helper are addressing the same page-visibility boundary. That needs to be paired with passing the owner's address country into the helper; otherwise the exact UK bank / UK citizenship / US address state can still be treated as "no documents needed" instead of showing the required proof-of-address upload.
I considered only adding an empty-state message on Documents, but that would keep an unnecessary page and still would not prompt for the proof-of-address document that the reported UK bank / US address state requires.
changed the title [-]“Upload Additional Documents” Page Appears with No Required Documents[/-][+][$250] “Upload Additional Documents” Page Appears with No Required Documents[/+]on May 13, 2026
Please re-state the problem that we are trying to solve in this issue.
In the Add Bank Account (Corpay / non-USD VBBA) flow, when a beneficial owner is configured with:
Bank account country: UK (GBP)
Citizenship / nationality: UK
Residential address: US
…the wizard reaches the Upload Additional Documentation page and displays only the heading + supporting copy. No upload fields are rendered, no document is required, and the user can advance the wizard by tapping Next with nothing attached.
Expected: either (a) the page is not shown when no document is required, or (b) the page is shown with at least one required upload field.
Actual: the page is shown empty.
Labeled Needs Reproduction because QA could not repro through their usual paths, but the gap is identifiable in source.
What is the root cause of that problem?
Two cooperating defects in the non-USD beneficial-owner flow:
The predicate that decides which document slots to render keys off nationality instead of residential-address country. For UK bank + UK nationality + US address, all four document flags evaluate false.
The wizard's skip-pages logic only suppresses the DOCUMENTS sub-step for one narrow case (UK bank ∧ UK nationality), and never asks "are any documents actually required right now?" So the page is mounted with all flags off and renders nothing but headings.
Detail:
1. getNeededDocumentsStatusForBeneficialOwner returns all-false for this combo
There is no top-level guard that early-returns when all four flags are false. The FormProvider still validates against STEP_FIELDS = [proofOfOwnership, addressProof, copyOfID, codiceFiscale], but getFieldRequiredErrors only errors on fields actually rendered as required — with zero upload widgets rendered, nothing blocks Submit.
3. The skip-pages predicate only knows about one narrow case
This skips DOCUMENTS only when bank country and nationality both equal GB. It doesn't call getNeededDocumentsStatusForBeneficialOwner to ask whether anything is actually required, so it can't catch the empty case for any other country combo.
This issue is the rendering-side symptom of the same data gap covered by #90494 (the proof-of-address predicate uses the wrong country field). Fixing the predicate alone closes the "page appears empty" symptom for the specific UK-bank-with-foreign-address case; adding a "skip page when nothing is required" guard makes the wizard self-consistent for any future combo where the four flags all collapse to false.
What changes do you think we should make in order to solve the problem?
This is the same change proposed in #90494. After this, the UK-bank/US-address case correctly returns isProofOfAddressNeeded = true, and Documents.tsx renders the proof-of-address upload widget — so the page is no longer empty.
This replaces the narrow bankCountry === GB && nationality === GB skip with a general "skip when nothing is required" rule. It subsumes the original narrow case (a UK-bank UK-national UK-resident genuinely needs no documents → skip), and also handles future country combos where all four flags are false.
Defense-in-depth in Documents.tsx: if the sub-step mounts with all four flags false anyway (e.g., a race where the parent's skip-pages memo hasn't recomputed), early-return / auto-advance:
This is small, local, and prevents the "empty page that the user can skip" UX in any edge case the parent skip-list misses.
Scope: three files. getNeededDocumentsStatusForBeneficialOwner.ts (+1 param, +1 branch), BeneficialOwnerDetailsFormPages.tsx (+1 draft read, replace narrow if with if (!isAnyDocumentNeeded)), Documents.tsx (+5 lines for the early-return / auto-advance). ~25 lines total. No API change, no Onyx schema change, no new translation strings. Platforms per the issue: Windows Chrome and MacOS Chrome/Safari — but the code path is shared, so the fix applies wherever the NonUSD flow runs.
This proposal is intentionally consistent with the proposal for #90494: change #1 is the same change there; changes #2 and #3 add the page-visibility hygiene that #90494 doesn't address.
What alternative solutions did you explore? (Optional)
Hard-code "always show at least one upload field on this page" (e.g., proof of address).Rejected: would over-collect documents from users who genuinely don't need anything (UK-bank UK-national UK-resident), regressing the original skip-pages intent.
Show a localized empty-state message ("no additional documents required") and an explicit "Continue" button when all flags are false, instead of skipping the page.Rejected: extra UI weight for a page the user has no reason to visit. The user is mid-flow; the right behavior is to move them forward, not to confirm "nothing to do here."
Move the skip decision into the parent stepper (useSubPage) by always computing getNeededDocumentsStatusForBeneficialOwner upstream.Rejected: equivalent to change Fix spaces #2 above but spread across the stepper rather than the form's skipPages array. Keeping the change in skipPages matches the existing pattern (SUB_PAGE_NAMES.LAST_4_SSN is already skipped there) and is a smaller diff.
Treat any UK bank with non-UK address as needing all four documents.Rejected: over-collects (proof of ownership and codice fiscale don't depend on the address-country mismatch). The targeted branch on isAddressCountryMismatch only flips proof-of-address, which is the Corpay rule the issue describes.
Please re-state the problem that we are trying to solve in this issue.
When a user adds a non-USD bank account with matching bank account country and beneficial owner nationality (e.g., UK bank account with UK citizenship beneficial owner), the "Upload Additional Documents" page appears with no required upload fields displayed. This prevents the user from understanding what documents are needed and allows them to skip a page that should either be hidden or display actual document requirements. The expected behavior is that if no documents are required, the page should not be shown at all.
What is the root cause of that problem?
The bug originates in BeneficialOwnerDetailsFormPages.tsx:79–88 in the skipPages function. The skip predicate only skips the DOCUMENTS subpage when countryStepCountryValue === GB && beneficialOwnerNationality === GB (hard-coded to GB/GB only). However, getNeededDocumentsStatusForBeneficialOwner returns all-false for any case where workspaceCurrency === GBP && beneficialOwnerNationality === GB, regardless of accountCountry. When this all-false condition holds, the Documents subpage renders only the header and description text but none of the conditional document requirement blocks (isProofOfOwnershipNeeded, isCopyOfIDNeeded, isProofOfAddressNeeded, isCodiceFiscaleNeeded), creating an empty page the user can skip.
The skip predicate is too narrow: it should be derived from the same getNeededDocumentsStatusForBeneficialOwner result that the Documents child component uses, not hard-coded to GB+GB. The function signature is getNeededDocumentsStatusForBeneficialOwner(currency, accountCountry, beneficialOwnerNationality) — all three parameters must be passed correctly; using the wrong country source (e.g. citizenship country in place of bank account country) would silently produce incorrect skip decisions.
What changes do you think we should make in order to solve the problem?
File:src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx Function:skipPages (useMemo at line 79) Description: Call getNeededDocumentsStatusForBeneficialOwner(currency, accountCountry, beneficialOwnerNationality) inside skipPages and skip the DOCUMENTS subpage when all four document flags are false. Replace the hard-coded GB+GB predicate with:
Then replace the hard-coded condition that skips DOCUMENTS with noDocumentsNeeded. The ?? '' fallbacks ensure that if any of workspaceCurrency, countryStepCountryValue, or beneficialOwnerNationality is null/undefined, the function receives a defined string; getNeededDocumentsStatusForBeneficialOwner treats an unrecognised currency/country as having no document requirements, so the page is correctly hidden rather than shown empty.
The three variables are already read from Onyx/form state earlier in the same component — countryStepCountryValue is the bank account country (the accountCountry parameter), not the citizenship country. Passing the citizenship nationality as accountCountry would be incorrect; the existing variable names already reflect the right mapping.
Blast radius: This change only affects the skip logic for the DOCUMENTS subpage in the beneficial owner details flow. It will cause the page to be hidden for all currency/country/nationality combinations where no documents are required (not just GB/GB), which is the intended behavior. No other callers depend on the skipPages array structure. The logic is pure (no side effects) and runs identically on web and mobile because getNeededDocumentsStatusForBeneficialOwner contains no platform-specific branches — it derives its result solely from the three string parameters.
What alternative solutions did you explore? (Optional)
Render-time early-return inside Documents.tsx: A render-time guard that calls onNext() when no documents are needed would cause a brief render of the empty page before navigating away and would conflict with the useSubPage flow pattern (which is designed to skip pages declaratively via skipPages). The parent-level skip is the correct extension point for this fix.
[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.
[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: N/A
[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:
Regression Test Proposal
Precondition:
Workspace with GBP output currency (Corpay NonUSD flow)
Test:
Start Add bank account flow from Workflows
Select UK as bank account country
Continue to the beneficial owner info step
Add a beneficial owner with nationality = UK and a US address
Continue through the owner sub-steps (Name > Nationality > Ownership % > DOB > Address)
Verify the flow skips the "Upload Additional Documents" page and goes straight to Confirmation
Regression: repeat with a non-UK nationality and verify the Documents page IS shown with the correct upload fields
Activity
MelvinBot commentedon May 13, 2026
Proposal
Problem
The "Upload Additional Documents" page renders with zero upload fields, allowing the user to skip it without providing required documentation.
Root Cause
There are two places this page can appear, and both have bugs:
1.
EnterSignerInfoflow (primary bug) —EnterSignerInfo/subSteps/UploadDocuments.tsx:38-39:The country is derived from the workspace currency via
mapCurrencyToCountry, NOT from the bank account country. For a USD workspace adding a UK bank account:currency = 'USD',mapCurrencyToCountry('USD')returns'US'getNeededDocumentsStatusForSignerInfo('USD', 'US')→ all flags false → empty page2.
NonUSD/SignerInfoflow (secondary bug) —SignerDetailsFormPages.tsx:24-31: TheUPLOAD_DOCUMENTSpage is never conditionally skipped, unlike the beneficial owner flow which skipsDOCUMENTSfor GB+GB. If any edge case causescountryto be empty in the draft, the page renders with no fields and no skip.Solution
Fix 1 (EnterSignerInfo): In
EnterSignerInfo/subSteps/UploadDocuments.tsx, read the bank account country from the reimbursement account data instead of deriving it from the workspace currency:This mirrors how
getCurrencyForNonUSDBankAccountreads country (from the draft/achData first, falling back to currency mapping).Fix 2 (skip logic): In
SignerDetailsFormPages.tsx, addUPLOAD_DOCUMENTStoskipPageswhen all document flags fromgetNeededDocumentsStatusForSignerInfoare false. This provides a safety net: if no documents are needed, the page is skipped entirely rather than shown empty.Similarly, add skip logic in
EnterSignerInfo/index.tsxbodyContentto conditionally excludeUploadDocuments.Investigation details
How
getNeededDocumentsStatusForSignerInfoevaluates for the reported scenario (USD workspace + UK bank account):isCopyOfIDNeededisAddressProofNeededisProofOfDirectorsNeededisCodiceFiscaleNeededisPRDAndFSGNeededWith the correct country (GB), at least
isAddressProofNeededwould be true, showing the address proof upload field.Related issue: #90494 ("Frontend Uses Wrong Country Field to Determine Proof of Address Requirement") describes the same root cause from a different angle — proof of address isn't prompted because the wrong country is used in the determination logic.
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.David-2002065 commentedon May 13, 2026
Proposal
What is the root cause of that problem?
BeneficialOwnerDetailsFormPagesdecides whether to skip the Documents sub-page with a single hand-rolled rule that only covers one specific scenario — bank country =GBAND nationality =GB:https://github.com/Expensify/App/blob/main/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx#L79-L88
The Documents sub-page itself unconditionally renders its three header strings ("Upload additional documentation", "Please upload…", "Accepted files…") and only gates the upload fields on the per-document flags — so if
getNeededDocumentsStatusForBeneficialOwnerreturns every flagfalse, the user sees a page with three labels, no inputs, and a working submit button:https://github.com/Expensify/App/blob/main/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Documents.tsx#L102-L143
So there are two sources of truth for "are documents needed?" that don't agree:
getNeededDocumentsStatusForBeneficialOwner) — the actual per-document rules.Whenever the rules agree that nothing is required but the skip rule misses the case, the user reaches an empty page. That's what's happening in the repro: with the orchestrator currently consulting only
nationalityandcountryStepCountryValue(no address country), the all-false output for UK/UK/US slips through, and even editing back into the page fromConfirmation.tsx#L90lands here.This issue is downstream of #90494 — proof of address should be required for UK/UK/US — but the empty-page failure mode is a separate UX bug: the orchestrator doesn't trust the rules helper.
What changes do you think we should make in order to solve the problem?
Make
getNeededDocumentsStatusForBeneficialOwnerthe single source of truth. Two coordinated changes:1. Derive
skipPagesfrom the rules helper inBeneficialOwnerDetailsFormPages.tsx:The fourth
beneficialOwnerAddressCountryargument matches the signature change proposed in #90494 — even if that PR ships first or later, the orchestrator gets correct skip behaviour as soon as the helper knows about the address country.2. Defense in depth — auto-advance from
Documents.tsxwhen no document is required, so deep links (e.g. editing into the page fromConfirmation) don't strand the user on an empty page:The orchestrator change is the real fix; the
Documents.tsxguard is a safety net for any direct navigation. Together they make "page renders ↔ at least one document is needed" an invariant enforced by the rules helper, not by parallel hardcoded conditions.What alternative solutions did you explore?
I considered keeping the orchestrator's hardcoded skip rule and just adding the
useEffect-based auto-advance insideDocuments.tsx. That would make the empty page un-reachable but would leave two parallel rule sources around, which is exactly the trap the current code fell into. Centralizing skip on the helper means future tweaks to "which docs are needed?" automatically propagate to "is the page shown?" without anyone remembering to update two files.I also considered rendering an explicit empty-state ("No documents required, continue") instead of skipping. It's a valid pattern, but for the bank account flow the page exists only to collect uploads — there's nothing for a user to read or confirm here — so showing it adds a click without value. Skip is the right call.
yusufdeveloper2903 commentedon May 13, 2026
Proposal
What is the root cause of that problem?
The Documents sub-step in the NonUSD beneficial-owner flow is gated by a narrow hardcoded special case that doesn't match the predicate that drives what's rendered inside the page, so the page can mount with all four content sections collapsed to
false.1. Skip rule and render rule are out of sync.
The page lists are computed in
BeneficialOwnerDetailsFormPages.tsx:App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx
Lines 34 to 43 in d63051f
App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx
Lines 79 to 88 in d63051f
skipPagesonly addsDOCUMENTSwhen the bank country in the draft is exactlyGBand the owner's nationality is exactlyGB. Meanwhile, what the Documents page actually renders is gated ongetNeededDocumentsStatusForBeneficialOwner(currency, country, beneficialOwnerNationality):App/src/pages/ReimbursementAccount/NonUSD/utils/getNeededDocumentsStatusForBeneficialOwner.ts
Lines 10 to 23 in d63051f
For workspace currency
GBP, bank countryGB, nationalityGB, addressUS, all four flags collapse tofalse:isProofOfOwnershipNeeded:EUR/AUD/CAD || (GBP && nationality !== GB)→ falseisCopyOfIDNeeded:GBP && nationality !== GB→ falseisProofOfAddressNeeded:EUR || isCopyOfIDNeeded→ falseisCodiceFiscaleNeeded:accountCountry === IT→ falseThe Documents component renders only those four sections (Documents.tsx L116‑L223), so the visible content is just the heading and two supporting paragraphs, and
useReimbursementAccountStepFormSubmithappily lets the user submit because all fields are optional.2. Where the special case actually fails.
The intent on
BeneficialOwnerDetailsFormPages.tsx:84is to catch this exact scenario, but it reads the bank country only fromreimbursementAccountDraft:App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx
Line 70 in d63051f
The Documents page reads the same country via
getCurrencyForNonUSDBankAccount, which falls back toreimbursementAccount.achData.countrywhen the draft is empty:App/src/pages/ReimbursementAccount/NonUSD/utils/getCurrencyForNonUSDBankAccount.ts
Line 14 in d63051f
So when the user enters the flow with
countryonly inachData(e.g. after a server-side hydration of the existing reimbursement account),countryStepCountryValueresolves to'', theGB && GBclause isfalse,DOCUMENTSis not skipped, and the empty page renders even thoughgetNeededDocumentsStatusForBeneficialOwner— which uses the fallback — produces all-false flags.What changes do you think we should make in order to solve the problem?
I'd derive the skip predicate from the same function that drives the page's render, instead of duplicating a narrow shape of it in the parent. That way, "page is empty" and "page is skipped" can't drift apart.
In
BeneficialOwnerDetailsFormPages.tsx:const skipPages = useMemo(() => { const pagesToSkip: string[] = []; if (beneficialOwnerNationality !== CONST.COUNTRY.US) { pagesToSkip.push(SUB_PAGE_NAMES.LAST_4_SSN); } - if (countryStepCountryValue === CONST.COUNTRY.GB && beneficialOwnerNationality === CONST.COUNTRY.GB) { - pagesToSkip.push(SUB_PAGE_NAMES.DOCUMENTS); - } + const docStatus = getNeededDocumentsStatusForBeneficialOwner(currency, countryStepCountryValue, beneficialOwnerNationality); + if (!docStatus.isProofOfOwnershipNeeded && !docStatus.isCopyOfIDNeeded && !docStatus.isProofOfAddressNeeded && !docStatus.isCodiceFiscaleNeeded) { + pagesToSkip.push(SUB_PAGE_NAMES.DOCUMENTS); + } return pagesToSkip; - }, [beneficialOwnerNationality, countryStepCountryValue]); + }, [beneficialOwnerNationality, countryStepCountryValue, currency]);This removes the GB‑GB hardcode, uses the achData‑aware country read so the predicate fires even when the draft is empty, and skips
DOCUMENTSfor any current/future combination where all four flags collapse tofalse(e.g. the GBP/UK/UK case from this report, and also whatever new flag rule lands when #90494 is fixed).useSubPagealready routes around skipped pages on bothnextPageandprevPage(useSubPage/index.tsx L47‑L72), so the existing back-button handler (L103‑L125) continues to work unchanged.What alternative solutions did you explore? (Optional)
Auto-advance from inside
Documents.tsxwith auseEffectthat callsonNext()when all four flags are false. It's a smaller diff and covers the case where a user lands on the page via a direct URL (whichskipPagesdoesn't block, sinceuseSubPageonly filters innextPage/prevPage). I'd avoid it as the primary fix though — it causes a visible flash of the empty page on mount and forces the next page's mount into a render cycle of the page being skipped. A complementary, smaller hardening if direct-URL navigation is a concern in practice, layered on top of theskipPagesfix above.KJ21-ENG commentedon May 13, 2026
🚨 Edited by proposal-police: This proposal was edited at 2026-05-13 13:45:01 UTC.
Proposal
Please re-state the problem that we are trying to solve in this issue.
The non-USD bank-account flow can show the beneficial-owner "Upload additional documentation" page with only the heading/copy and no upload controls. In the reported UK bank account / UK citizenship / US address case, the user reaches an owner-info upload step that either should request proof of address or should be skipped when no documents are required.
What is the root cause of that problem?
The screenshot is the beneficial-owner flow:
BeneficialOwnerDetailsFormPagesrenders theOwner infostep and includes theDOCUMENTSsubpage in the owner page list:App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx
Lines 34 to 42 in 9d65949
That parent page decides whether to skip
DOCUMENTSwith a separate hardcoded predicate based only on bank country from the draft and owner nationality:App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx
Lines 68 to 88 in 9d65949
But the document page itself uses
getCurrencyForNonUSDBankAccount(...)andgetNeededDocumentsStatusForBeneficialOwner(...)to decide which upload controls to render:App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Documents.tsx
Lines 29 to 40 in 9d65949
The helper never receives the beneficial owner's residential address country. For the reported state (
currency = GBP, bank countryGB, nationalityGB, address countryUS), the existing helper returns all document flags false because it only checks currency, bank country, and nationality:App/src/pages/ReimbursementAccount/NonUSD/utils/getNeededDocumentsStatusForBeneficialOwner.ts
Lines 10 to 22 in 9d65949
When all four flags are false,
Documentsstill renders the static upload header/copy while every upload field block is gated off:App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Documents.tsx
Lines 113 to 223 in 9d65949
So two sources of truth drift apart: the parent decides page visibility with a narrow draft-only GB/GB rule, while the child decides visible uploads with a helper that ignores the owner's address country. That combination allows the owner documents page to mount with no required controls.
What changes do you think we should make in order to solve the problem?
Add the beneficial owner's residential address country to the document-requirement contract. In
getNeededDocumentsStatusForBeneficialOwner, accept a fourthbeneficialOwnerAddressCountryargument and makeisProofOfAddressNeededtrue when both countries are known and the owner address country differs from the bank account country. The address field already exists asBENEFICIAL_OWNER_DATA.COUNTRY:App/src/CONST/index.ts
Lines 776 to 792 in 9d65949
Then update the two current beneficial-owner callers:
BeneficialOwnerDetailsFormSubSteps/Documents.tsx, read${PREFIX}_${ownerBeingModifiedID}_${COUNTRY}from the reimbursement account draft and pass it withcurrency, bankcountry, and nationality. This makes the reported UK bank / UK nationality / US address case render the proof-of-address upload instead of an empty page.BeneficialOwnerDetailsFormSubSteps/Confirmation.tsx, pass the same owner address country into the helper so the confirmation summary and edit links use the same document flags as the upload page:App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Confirmation.tsx
Lines 21 to 27 in 9d65949
Finally, in
BeneficialOwnerDetailsFormPages.tsx, replace the hardcodedcountryStepCountryValue === GB && beneficialOwnerNationality === GBskip with the same helper result. Subscribe toONYXKEYS.REIMBURSEMENT_ACCOUNTand the policy, usegetCurrencyForNonUSDBankAccount(...)for the bank country/currency source, read the owner address country from the draft, then skipSUB_PAGE_NAMES.DOCUMENTSonly when all four helper flags are false. That keeps the page-list decision aligned with the fields actually rendered byDocuments.Scope boundaries:
src/pages/ReimbursementAccount/NonUSD/utils/getNeededDocumentsStatusForBeneficialOwner.ts- helper signature andisProofOfAddressNeeded;src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Documents.tsx- owner address country read and helper call;src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Confirmation.tsx- helper call for document summary rows;src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx-skipPagescalculation.What alternative solutions did you explore? (Optional)
MelvinBot pointed at
EnterSignerInfo/signer upload logic, but the attached media shows the owner-info panel and the owner-specific "direct or indirect owner of 25% or more" copy, so the signer page is not the failing page in this issue. The signer helper also already forces address proof for a GB bank account, which does not explain the empty owner page shown here.Human proposals that derive the parent skip from the beneficial-owner helper are addressing the same page-visibility boundary. That needs to be paired with passing the owner's address country into the helper; otherwise the exact UK bank / UK citizenship / US address state can still be treated as "no documents needed" instead of showing the required proof-of-address upload.
I considered only adding an empty-state message on
Documents, but that would keep an unnecessary page and still would not prompt for the proof-of-address document that the reported UK bank / US address state requires.melvin-bot commentedon May 13, 2026
Triggered auto assignment to Contributor-plus team member for initial proposal review - @abzokhattab (
External)[-]“Upload Additional Documents” Page Appears with No Required Documents[/-][+][$250] “Upload Additional Documents” Page Appears with No Required Documents[/+]melvin-bot commentedon May 13, 2026
Job added to Upwork: https://www.upwork.com/jobs/~022054554899234499987
Abdulloh0109 commentedon May 13, 2026
Proposal
Please re-state the problem that we are trying to solve in this issue.
In the Add Bank Account (Corpay / non-USD VBBA) flow, when a beneficial owner is configured with:
…the wizard reaches the Upload Additional Documentation page and displays only the heading + supporting copy. No upload fields are rendered, no document is required, and the user can advance the wizard by tapping Next with nothing attached.
Labeled
Needs Reproductionbecause QA could not repro through their usual paths, but the gap is identifiable in source.What is the root cause of that problem?
Two cooperating defects in the non-USD beneficial-owner flow:
false.Detail:
1.
getNeededDocumentsStatusForBeneficialOwnerreturns all-false for this combogetNeededDocumentsStatusForBeneficialOwner.ts#L10-L23:For GBP / UK bank / UK nationality / US address:
workspaceCurrency === GBP✓,nationality !== GB✗ →isCopyOfIDNeeded = falseworkspaceCurrency === EUR✗ →isProofOfAddressNeeded = falseisProofOfOwnershipNeededis also false (EUR/AUD/CAD don't apply; GBP+non-GB nationality doesn't apply)isCodiceFiscaleNeededis false (not Italy)All four are false. The function never reads the BO's residential address country, so the US address never affects the result.
2. The
Documentssub-step renders nothing but headings when all four are falseDocuments.tsx#L98-L215:There is no top-level guard that early-returns when all four flags are false. The
FormProviderstill validates againstSTEP_FIELDS = [proofOfOwnership, addressProof, copyOfID, codiceFiscale], butgetFieldRequiredErrorsonly errors on fields actually rendered as required — with zero upload widgets rendered, nothing blocks Submit.3. The skip-pages predicate only knows about one narrow case
BeneficialOwnerDetailsFormPages.tsx#L79-L88:This skips DOCUMENTS only when bank country and nationality both equal GB. It doesn't call
getNeededDocumentsStatusForBeneficialOwnerto ask whether anything is actually required, so it can't catch the empty case for any other country combo.This issue is the rendering-side symptom of the same data gap covered by #90494 (the proof-of-address predicate uses the wrong country field). Fixing the predicate alone closes the "page appears empty" symptom for the specific UK-bank-with-foreign-address case; adding a "skip page when nothing is required" guard makes the wizard self-consistent for any future combo where the four flags all collapse to false.
What changes do you think we should make in order to solve the problem?
Fix the predicate to account for residential-address country in
getNeededDocumentsStatusForBeneficialOwner.ts#L10-L23:This is the same change proposed in #90494. After this, the UK-bank/US-address case correctly returns
isProofOfAddressNeeded = true, andDocuments.tsxrenders the proof-of-address upload widget — so the page is no longer empty.Add a "nothing required" skip in
BeneficialOwnerDetailsFormPages.tsx#L79-L88:This replaces the narrow
bankCountry === GB && nationality === GBskip with a general "skip when nothing is required" rule. It subsumes the original narrow case (a UK-bank UK-national UK-resident genuinely needs no documents → skip), and also handles future country combos where all four flags are false.Defense-in-depth in
Documents.tsx: if the sub-step mounts with all four flags false anyway (e.g., a race where the parent's skip-pages memo hasn't recomputed), early-return / auto-advance:This is small, local, and prevents the "empty page that the user can skip" UX in any edge case the parent skip-list misses.
Scope: three files.
getNeededDocumentsStatusForBeneficialOwner.ts(+1 param, +1 branch),BeneficialOwnerDetailsFormPages.tsx(+1 draft read, replace narrowifwithif (!isAnyDocumentNeeded)),Documents.tsx(+5 lines for the early-return / auto-advance). ~25 lines total. No API change, no Onyx schema change, no new translation strings. Platforms per the issue: Windows Chrome and MacOS Chrome/Safari — but the code path is shared, so the fix applies wherever the NonUSD flow runs.This proposal is intentionally consistent with the proposal for #90494: change #1 is the same change there; changes #2 and #3 add the page-visibility hygiene that #90494 doesn't address.
What alternative solutions did you explore? (Optional)
Hard-code "always show at least one upload field on this page" (e.g., proof of address). Rejected: would over-collect documents from users who genuinely don't need anything (UK-bank UK-national UK-resident), regressing the original skip-pages intent.
Show a localized empty-state message ("no additional documents required") and an explicit "Continue" button when all flags are false, instead of skipping the page. Rejected: extra UI weight for a page the user has no reason to visit. The user is mid-flow; the right behavior is to move them forward, not to confirm "nothing to do here."
Move the skip decision into the parent stepper (
useSubPage) by always computinggetNeededDocumentsStatusForBeneficialOwnerupstream. Rejected: equivalent to change Fix spaces #2 above but spread across the stepper rather than the form'sskipPagesarray. Keeping the change inskipPagesmatches the existing pattern (SUB_PAGE_NAMES.LAST_4_SSNis already skipped there) and is a smaller diff.Treat any UK bank with non-UK address as needing all four documents. Rejected: over-collects (proof of ownership and codice fiscale don't depend on the address-country mismatch). The targeted branch on
isAddressCountryMismatchonly flips proof-of-address, which is the Corpay rule the issue describes.aswin-s commentedon May 13, 2026
Please re-state the problem that we are trying to solve in this issue.
When a user adds a non-USD bank account with matching bank account country and beneficial owner nationality (e.g., UK bank account with UK citizenship beneficial owner), the "Upload Additional Documents" page appears with no required upload fields displayed. This prevents the user from understanding what documents are needed and allows them to skip a page that should either be hidden or display actual document requirements. The expected behavior is that if no documents are required, the page should not be shown at all.
What is the root cause of that problem?
The bug originates in
BeneficialOwnerDetailsFormPages.tsx:79–88in theskipPagesfunction. The skip predicate only skips the DOCUMENTS subpage whencountryStepCountryValue === GB && beneficialOwnerNationality === GB(hard-coded to GB/GB only). However,getNeededDocumentsStatusForBeneficialOwnerreturns all-false for any case whereworkspaceCurrency === GBP && beneficialOwnerNationality === GB, regardless ofaccountCountry. When this all-false condition holds, the Documents subpage renders only the header and description text but none of the conditional document requirement blocks (isProofOfOwnershipNeeded,isCopyOfIDNeeded,isProofOfAddressNeeded,isCodiceFiscaleNeeded), creating an empty page the user can skip.The skip predicate is too narrow: it should be derived from the same
getNeededDocumentsStatusForBeneficialOwnerresult that the Documents child component uses, not hard-coded to GB+GB. The function signature isgetNeededDocumentsStatusForBeneficialOwner(currency, accountCountry, beneficialOwnerNationality)— all three parameters must be passed correctly; using the wrong country source (e.g. citizenship country in place of bank account country) would silently produce incorrect skip decisions.App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsx
Lines 83 to 86 in 9d65949
App/src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormSubSteps/Documents.tsx
Lines 26 to 50 in 9d65949
What changes do you think we should make in order to solve the problem?
src/pages/ReimbursementAccount/NonUSD/BeneficialOwnerInfo/BeneficialOwnerDetailsFormPages.tsxFunction:
skipPages(useMemo at line 79)Description: Call
getNeededDocumentsStatusForBeneficialOwner(currency, accountCountry, beneficialOwnerNationality)insideskipPagesand skip the DOCUMENTS subpage when all four document flags are false. Replace the hard-coded GB+GB predicate with:Then replace the hard-coded condition that skips DOCUMENTS with
noDocumentsNeeded. The?? ''fallbacks ensure that if any ofworkspaceCurrency,countryStepCountryValue, orbeneficialOwnerNationalityis null/undefined, the function receives a defined string;getNeededDocumentsStatusForBeneficialOwnertreats an unrecognised currency/country as having no document requirements, so the page is correctly hidden rather than shown empty.The three variables are already read from Onyx/form state earlier in the same component —
countryStepCountryValueis the bank account country (theaccountCountryparameter), not the citizenship country. Passing the citizenship nationality asaccountCountrywould be incorrect; the existing variable names already reflect the right mapping.Blast radius: This change only affects the skip logic for the DOCUMENTS subpage in the beneficial owner details flow. It will cause the page to be hidden for all currency/country/nationality combinations where no documents are required (not just GB/GB), which is the intended behavior. No other callers depend on the
skipPagesarray structure. The logic is pure (no side effects) and runs identically on web and mobile becausegetNeededDocumentsStatusForBeneficialOwnercontains no platform-specific branches — it derives its result solely from the three string parameters.What alternative solutions did you explore? (Optional)
Render-time early-return inside Documents.tsx: A render-time guard that calls
onNext()when no documents are needed would cause a brief render of the empty page before navigating away and would conflict with theuseSubPageflow pattern (which is designed to skip pages declaratively viaskipPages). The parent-level skip is the correct extension point for this fix.40 remaining items
yusufdeveloper2903 commentedon Jul 2, 2026
@mallenexpensify Thanks! I've accepted the job offer on Upwork
mallenexpensify commentedon Jul 2, 2026
@yusufdeveloper2903 paid, summary updated above. Thx.
@abzokhattab plz complete the BZ checklist and tag me in a post once you have. Thx
melvin-bot commentedon Jul 9, 2026
@mallenexpensify Whoops! This issue is 2 days overdue. Let's get this updated quick!
mallenexpensify commentedon Jul 9, 2026
@abzokhattab plz complete the BZ checklist and tag me in a post once you have. Thx
melvin-bot commentedon Jul 10, 2026
@abzokhattab Eep! 4 days overdue now. Issues have feelings too...
abzokhattab commentedon Jul 12, 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: [CBN] Non-USD flow refactor #83308 (comment)
[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: N/A
[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:
Regression Test Proposal
Precondition:
Test:
Do we agree 👍 or 👎
abzokhattab commentedon Jul 12, 2026
@mallenexpensify done
quinthar commentedon Aug 19, 2026
Approved $250 to @abzokhattab