> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fusioncore.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Portal Troubleshooting

> Fast symptom-to-fix reference for the fusionCore Portal: setup, checkout, roster, the Subscription Hub, wallet items, and cancellation.

If something isn't working in the Portal, find the symptom below.

## Portal Setup

<AccordionGroup>
  <Accordion title="Guests can see Orders they shouldn't be able to see">
    **What you see:** A guest (not-logged-in) visitor reaches a checkout or order page and can view Orders, Financial Events, or payment details that should be private.

    **Why:** The Portal does not gate guests itself — its order access check returns true for any guest user. All guest access control comes from the standard Experience Cloud guest user profile and the site's public-access sharing settings. An overly broad guest profile exposes those records.

    **Fix:** Tighten the Experience Cloud guest user profile and the site's public access to the minimum your public pages need, then re-test as a guest before launch. There is no fusionCore field that controls this. See [Enabling Guest Portal Users](/end-user-guides/portal/enabling-guest-portal-users).
  </Accordion>

  <Accordion title="A fusionCore component isn't in the Experience Builder palette, or doesn't render">
    **What you see:** You can't find a fusionCore component in the Components list, or you placed one and it shows nothing.

    **Why:** fusionCore Portal components target Experience Builder pages only. They do not appear on, and will not render on, internal Lightning record pages or Lightning app pages.

    **Fix:** Confirm you are editing an **Experience Cloud site** in Experience Builder, not an internal Lightning page. See [Setting Up a Portal Site](/end-user-guides/portal/setting-up-a-portal-site) and [Creating Portal Site Pages](/end-user-guides/portal/creating-portal-site-pages).
  </Accordion>

  <Accordion title="A customization disappeared after a package upgrade">
    **What you see:** A change you made to a Portal component or its code is gone after an upgrade, and the shipped behavior is back.

    **Why:** The customizable Portal Components package has no namespace, so you can edit its components in place — but a package upgrade overwrites any in-place code edit. Configuration-only changes (component properties, field sets) survive upgrades; in-place **code** edits do not. The managed checkout and payment components cannot be edited at all.

    **Fix:** For code changes, clone the component first (a renamed copy), apply your changes to the clone, and point your Experience page at the copy so upgrades leave it alone. Configuration changes need no clone. See the clone guidance in the [Portal Overview](/end-user-guides/portal/index).
  </Accordion>
</AccordionGroup>

## Checkout

<AccordionGroup>
  <Accordion title="The checkout page shows an error instead of a payment form">
    **What you see:** The checkout page loads a message or error rather than a pay form.

    **Why:** Checkout is intentionally blocked when the Order can't be paid. Common blocked states: the Order is a Draft, already Fully Paid, Voided, or Written-Off; its price or tax calculation is still in progress or not yet calculated; it has pending or action-required Financial Events; it has no items; or a discount-code item still needs changes.

    **Fix:** Open the Order and confirm it is in a payable state — items present, calculation complete, not already paid or voided, no Financial Events awaiting action — then return to checkout. See [Checkout (LWC)](/end-user-guides/portal/checkout-lwc/index).
  </Accordion>

  <Accordion title="Checkout says &#x22;Missing Order or Installment context&#x22;">
    **What you see:** Instead of a pay form, the page reports it is missing an Order or installment.

    **Why:** The checkout component reads which Order to pay from a URL parameter (for example `?orderId=`), not from a record bound to the page. A link without that parameter gives the component nothing to load.

    **Fix:** Build every link to the checkout page with the Order's UUID in the parameter the component expects. See [Checkout (LWC)](/end-user-guides/portal/checkout-lwc/index) and [Configuring the Business Unit's Portal Checkout URL](/end-user-guides/portal/checkout-lwc/configuring-the-business-units-portal-checkout-page).
  </Accordion>

  <Accordion title="A guest can't pay an order that has an auto-charge item">
    **What you see:** A guest reaches checkout for an Order containing an auto-charge (stored-method) item and is blocked from paying.

    **Why:** Guest payment of auto-charge Orders is disabled by default. The Portal blocks it unless your org has explicitly enabled guest payments for auto-charge items.

    **Fix:** Either have the user log in to pay, or enable guest payments for auto-charge items in your org's Portal settings if that fits your policy. See [Enabling Guest Portal Users](/end-user-guides/portal/enabling-guest-portal-users).
  </Accordion>

  <Accordion title="The wrong fields — or no fields — appear at checkout">
    **What you see:** The checkout display shows fields you didn't expect, or is missing the fields you configured.

    **Why:** Checkout picks a field set by customer type (individual vs. organization) and by Order vs. installment. The field set it uses is named in a configuration record; if that name points to a field set that doesn't exist on the matching object, the wrong scenario's fields — or none — appear.

    **Fix:** Confirm the named field set actually exists on the correct object before saving the configuration. See [Configuring Field Sets for Portal Checkout](/end-user-guides/portal/checkout-lwc/configuring-field-sets-for-portal-checkout).
  </Accordion>
</AccordionGroup>

## Payment Confirmation

<AccordionGroup>
  <Accordion title="The payment confirmation page errors after a payment">
    **What you see:** After paying, the user lands on the confirmation page and it shows an error instead of the receipt.

    **Why:** The confirmation component needs a payment context in the URL and a populated receipt field. It errors if no Financial Event (or Payment Provider Event) is passed, if the receipt URL field it reads is empty when the user arrives, if that record is not a payment, or if the receipt value isn't a valid `http(s)://` link.

    **Fix:** Make sure your install order and automation populate the receipt URL field before checkout redirects the user, that the field name configured on the component is a real field, and that the receipt value is a full web link. See [Payment Confirmation](/end-user-guides/portal/checkout-lwc/payment-confirmation).
  </Accordion>

  <Accordion title="A receipt or &#x22;View Document&#x22; link lands on a &#x22;site cannot be reached&#x22; page">
    **What you see:** Clicking a receipt, **View Document**, or **View Summary Document** link sends the user to a broken page that won't load.

    **Why:** The document links are built from your Business Unit's Portal URL. If that URL's format differs from what the link formula expects (for example, your live site domain doesn't include the extra site-name path segment that sandbox/scratch domains have), the generated link points to a page that doesn't exist.

    **Fix:** Confirm the Business Unit Portal URL exactly matches your live site's domain format. If the packaged document-link formulas still don't match your domain, your implementation team can adjust them to your domain — back the change up, because a package upgrade can overwrite it. See [Configuring the Business Unit's Portal Checkout URL](/end-user-guides/portal/checkout-lwc/configuring-the-business-units-portal-checkout-page).
  </Accordion>
</AccordionGroup>

## Roster (Portal Order Page)

<AccordionGroup>
  <Accordion title="The roster table is empty or shows nothing">
    **What you see:** The portal Order/roster page renders no table, or the table has no rows or no action buttons.

    **Why:** The roster table is rendered by the **FS Roster accelerator** — a separate, separately installed package, not part of the managed Portal. If it isn't installed, the component isn't available and nothing renders. Even when installed, a roster setting record drives what it shows: a half-configured Business Unit leaves the Order action links blank (with no error), and an installment link only appears when there's a next installment to pay.

    **Fix:** Confirm the FS Roster accelerator is installed, that the Business Unit's Portal URL and page-path fields are set, and that a roster setting record exists pointing at the right object and fields. See [Adding Roster Settings to the Portal Site](/end-user-guides/portal/portal-order-page-roster-settings/adding-roster-settings-to-portal-site) and [Creating Roster Setting Records for Orders and Payments](/end-user-guides/portal/portal-order-page-roster-settings/creating-roster-setting-records-for-orders-and-payments).
  </Accordion>

  <Accordion title="The roster shows records that belong to other users">
    **What you see:** A logged-in portal user sees rows in the roster that aren't theirs.

    **Why:** The roster's filter is a raw query the admin writes. If that query has no clause scoping results to the logged-in user, the table returns everyone's records.

    **Fix:** Add a user-scoping clause to the roster setting's query (the roster supports a token for the logged-in user). See [Creating Roster Setting Records for Orders and Payments](/end-user-guides/portal/portal-order-page-roster-settings/creating-roster-setting-records-for-orders-and-payments).
  </Accordion>
</AccordionGroup>

## Subscription Hub

<AccordionGroup>
  <Accordion title="A subscription a member owns isn't showing in the Subscription Hub">
    **What you see:** A member opens the Subscription Hub and a subscription they own is missing.

    **Why:** The hub shows a subscription only when the member's contact role is listed in that product's **Subscription Visibility** setting. An empty visibility setting hides the subscription from everyone, including its owner.

    **Fix:** On the subscription's product, add the appropriate roles (for example, Subscription Contact) to **Subscription Visibility**. See [Managing and Renewing Subscriptions in the Subscription Hub](/end-user-guides/portal/subscription-hub/managing-and-renewing-subscriptions-in-subscription-hub).
  </Accordion>

  <Accordion title="A member can see a subscription but gets &#x22;not eligible to manage&#x22;">
    **What you see:** The subscription appears in the hub, but Manage or Manage Benefits reports the member isn't allowed.

    **Why:** Seeing a subscription and managing it are governed by two separate product settings. A member who is in **Subscription Visibility** but not in **Manage Subscription** can view but not manage. Manage Benefits requires both.

    **Fix:** Add the member's contact role to the product's **Manage Subscription** setting as well. See [Managing Benefit Allocations for the Subscription Hub](/end-user-guides/portal/subscription-hub/managing-benefit-allocations-for-subscription-hub).
  </Accordion>

  <Accordion title="Manage or Renew links go to the site root instead of the right page">
    **What you see:** Clicking Manage or Renew in the hub lands on the site home page, not the manage/renew page.

    **Why:** The Subscription Hub component has required properties for the manage page and the renew page. They default to `/`, and if left at `/` the links resolve to the site root with no error.

    **Fix:** In Experience Builder, set the hub's manage-page and renew-page properties to the actual pages that host the manage and renew components. See [Managing and Renewing Subscriptions in the Subscription Hub](/end-user-guides/portal/subscription-hub/managing-and-renewing-subscriptions-in-subscription-hub).
  </Accordion>

  <Accordion title="The Manage Benefits page is blank or says you have no access">
    **What you see:** The Manage Benefits page shows nothing, or reports that you don't have access.

    **Why:** The page loads a subscription from a UUID in its URL (`?id=`), which the Subscription Hub passes automatically — opening the page directly leaves it with nothing. Access also requires the member's contact role to be in **both** the product's Subscription Visibility and Manage Subscription settings.

    **Fix:** Reach Manage Benefits through the hub's manage flow (so the id is passed), and confirm the member's role is in both product settings. See [Managing Benefit Allocations for the Subscription Hub](/end-user-guides/portal/subscription-hub/managing-benefit-allocations-for-subscription-hub) and the [Manage Benefits Page](/end-user-guides/portal/subscription-hub/manage-benefits-page).
  </Accordion>
</AccordionGroup>

## Wallet Items

<AccordionGroup>
  <Accordion title="The wallet is empty, or no payment methods show in Choose from Wallet">
    **What you see:** A portal user's wallet shows no saved methods, or the **Choose from Wallet** modal at checkout is empty.

    **Why:** Saved methods require a configured and validated Stripe Payment Provider Account — without one, there is nothing to store methods against, so the wallet has nothing to show. Portal users also need the wallet permission set, which grants the record access and controllers the wallet depends on.

    **Fix:** Configure and validate your Stripe Payment Provider Account first, and assign the wallet permission set to portal users. See [Wallet Item Page](/end-user-guides/portal/wallet-item-page) and [Creating Wallet Items as a Staff User](/end-user-guides/accounts/wallet-items/creating-wallet-items-as-a-staff-user).
  </Accordion>

  <Accordion title="Wallet Items fail to load, or you get a &#x22;Choose from Wallet&#x22; / record-page error">
    **What you see:** The wallet component fails to load, the **Choose from Wallet** modal stays empty even with a validated Payment Provider Account, or opening a Wallet Item record page throws an error. You may also see the **Manage Wallet** quick action prompt for a Payment Provider Account and then show no list to pick from.

    **Why:** The Wallet Item component field for the payment type you're saving isn't populated. When required fields on the Wallet Item are missing, the wallet UI can't render the entry and the record page errors.

    **Fix:** Make sure the required fields on the Wallet Item (and the payment type) are populated. If wallet items still won't load after Stripe is validated, have your implementation team confirm the Wallet Item record has all the fields the component expects. See [Editing Wallet Items](/end-user-guides/accounts/wallet-items/editing-wallet-items).
  </Accordion>

  <Accordion title="A wallet item I deleted is still there">
    **What you see:** A removed payment method still appears, or a method seems to vanish after you edit it.

    **Why:** Wallet items are soft-deleted, not hard-deleted — removal flags the record (and detaches it at the provider) rather than erasing it, so it leaves the active list but the record persists. Separately, editing any detail other than the nickname retires the original method and creates a new one, because stored payment details can't be altered at the provider.

    **Fix:** This is expected behavior. The removed or replaced method drops out of the active list; you don't need to do anything. See [Editing Wallet Items](/end-user-guides/accounts/wallet-items/editing-wallet-items).
  </Accordion>

  <Accordion title="The Saved Payments option doesn't appear for a staff user">
    **What you see:** A staff user paying an Order doesn't see the **Saved Payments** option.

    **Why:** Paying with a saved method as staff requires a specific pay-with-wallet permission set. Without it, the option is hidden.

    **Fix:** Assign the staff pay-with-wallet permission set. See [Paying with Wallet Items](/end-user-guides/accounts/wallet-items/paying-with-wallet-items).
  </Accordion>
</AccordionGroup>

## Cancel Subscription

<AccordionGroup>
  <Accordion title="The portal Cancel Subscription link is blank">
    **What you see:** The cancel link in the Subscription Hub is empty, so the member can't start a cancellation.

    **Why:** The link renders only when all of these are true: the subscription is Active or Pending, the Business Unit's Portal URL and cancel page path are both set, the subscription has its UUID, and it isn't already cancelled. A blank link is almost always an unset cancel page path on the Business Unit.

    **Fix:** Set the cancel page path (and Portal URL) on the Business Unit, and confirm the subscription is Active or Pending and not already cancelled. See [Cancel Subscription](/end-user-guides/portal/subscription-hub/cancel-subscription).
  </Accordion>

  <Accordion title="A billing or primary contact can't cancel an organization's subscription">
    **What you see:** A contact who isn't the subscription's own contact (for example the account's billing or primary contact) can't cancel an organization subscription.

    **Why:** By default, only the subscription's own contact can cancel. Letting the account's billing contact or primary contact cancel organization subscriptions are separate org settings that ship turned off.

    **Fix:** If your policy allows it, enable the billing-contact and/or primary-contact cancel settings in your org. Otherwise the subscription's own contact must cancel. For cancellation behavior and eligibility, see [Subscription Cancellation](/end-user-guides/subscriptions/subscription-cancellation) and the placement steps on [Cancel Subscription](/end-user-guides/portal/subscription-hub/cancel-subscription).
  </Accordion>

  <Accordion title="Cancelling the subscription didn't refund or end it immediately">
    **What you see:** A member cancels through the portal but the subscription stays active until the end of its term and no refund is issued.

    **Why:** The portal cancel action cancels the **renewal** only. It does not refund or end the current term early.

    **Fix:** This is expected. The subscription runs to the end of its current term and will not auto-renew. For full behavior, see [Subscription Cancellation](/end-user-guides/subscriptions/subscription-cancellation).
  </Accordion>
</AccordionGroup>