Troubleshooting portals

Q: The portal shows data we never meant to publish. Where do I look?

Check the Data Views tab of every portal, not just the one you were editing. All your portals share one anonymous visitor identity, so the public data views of all of them together decide what anonymous visitors can read. Deactivate any view that should not be public; it stops serving at once. Then review the Portal Anonymous profile for extra grants. Grants on other entities are not removed automatically. If the portal is also a storefront, review its catalogue separately. How portal security works walks through the full review.

This page helps an administrator find out why a portal, a portal page, a data list, signup or sign-in is not behaving as expected. Portals follow strict serving rules, so almost every problem comes down to one switch, one state or one membership. Work through the checks in the order given and stop at the first one that explains what you see.

Portal problems usually come from a visitor or a colleague: "the link says 404", "the products list is broken", "I signed up and nothing happened". Each section below starts from that kind of report. For the full rules behind each check, see the linked pages for setting up, publishing and securing a portal.

How xMatix handles it

A request to a portal passes these gates in order. The first one that fails decides what the visitor sees.

The address resolves. The hostname must be the portal's platform address registered at publish, or a custom domain that reads Verified.
The Portals module is on. Enable Portals must be on for your organization.
The site is servable. It must be published and Active.
The visitor is admitted to the site. With Anonymous visitors off, only signed-in members of this portal and your own staff get past this gate. Everyone else gets the 404 page.
The page is servable. It must be published. Signed-in-only pages need a signed-in member.
The page has content. It shows its published layout, or the list from its embedded data view.
The data view serves. It must be active, and it runs as the anonymous visitor identity (public views) or as the signed-in visitor (signed-in-only views), within that identity's own access.

A site, page or data view that fails a gate returns a plain "not found" (HTTP 404), not an explanation. This is deliberate: a portal never tells an outsider that a hidden page exists. As a result, most symptoms look the same to the visitor, and you find the cause in Setup.

Prerequisites

The Manage portals capability, to open Setup → Feature Hub → Portals → Portals and the portal's detail page.
For the module switch, the Feature Hub settings capability, to open Setup → Feature Hub → Portals → Settings.
For custom domains, access to Setup → Feature Hub → Platform → Domains.
The exact address the visitor used, the page path, and whether the visitor was signed in. These three facts decide which section below applies.

Procedure

Use this order for every portal report.

Step 1 — Find the portal in the register

Open Setup → Feature Hub → Portals → Portals and find the portal by label or slug. Read its row:

Published should read Published, not Draft.
Status should read Active, not Inactive.
Anonymous reads Allowed for a portal anyone can open, or Sign-in only for a members-only portal.
Address is the platform address. If you hover over the address of an unpublished portal, the tooltip says it returns 404.

If there is no row for the portal, the address can't serve one. Find the intended portal before you create a new one, because a duplicate gets a different slug and a different address.

Step 2 — Reproduce as the visitor

Open the address in a private browser window, so you are not signed in, and go to the path the visitor reported. If the visitor was signed in, sign in with a member account for that portal. Do not use your own staff account: staff count as signed in on every portal, so you see pages a customer can't see.

Step 3 — Match the symptom

Find what you saw in the sections below and work through the checks in order.

Step 4 — Fix, then wait for caches

Most fixes apply at once. The exception is an address that was just registered: an address the portal couldn't find is remembered for up to 30 seconds, and a known address is remembered for up to 5 minutes. Wait a minute and try again before you dig deeper.

Common problems: the portal does not load

The address shows "404 | This page could not be found."

This is what a visitor sees whenever the site is not served. Check these, in order:

The site is not published. On the portal's detail page the header shows State: Draft, the address has a Draft tag, and the header button reads Publish. Click Publish and confirm. The toast reads "Portal published". Publishing the site does not publish its pages; each page needs its own Publish draft.
The site is inactive. The Active switch on the General tab overrides the publish state. A published site that is not active serves nothing. Switch it on and click Save.
Anonymous visitors is off and the visitor is not signed in. With Anonymous visitors off, visitors who are not signed in get the 404 page. They are not sent to the sign-in screen. New portals start with this switch off. Either switch Anonymous visitors on and save, or give the visitor the portal's /login address to sign in first.
The visitor is signed in, but to a different portal. Membership is per portal. A member of one of your portals counts as an anonymous visitor on another. On a sign-in-only portal that means the 404 page. Add them to this portal from its Members tab.
Enable Portals is off. When the switch at Setup → Feature Hub → Portals → Settings is off, every portal in the organization returns 404. Your portal configuration is kept.
The slug changed after publishing. The address is registered when you publish. A slug changed later is not registered, and the old address stops serving the site. Click Unpublish, then Publish.
You published a moment ago. Wait up to a minute and reload (see Step 4).

The custom domain shows the 404 page

A domain only routes; the site still has to be servable. Check that the domain's row on Setup → Feature Hub → Platform → Domains reads Verified (not Pending DNS) and that its type is Portal. Then run every check in the section above, because a verified domain in front of an unpublished or inactive site still returns 404. The DNS steps are in Publishing, hostnames and custom domains.

The sign-in screen reads the portal's theme and signup setting the way an anonymous visitor would. When Anonymous visitors is off, that read is refused, so the screen falls back to neutral branding, hides the account-creation link, and sends /signup back to /login. Members can still sign in. If you want branding and self-service signup, switch Anonymous visitors on and make sure only public data views hold public information.

A visitor gets a generic error page instead of a 404

If the portal service is overloaded or rate-limits the visitor while it loads the site or a page, the visitor sees a generic error page. Ask them to wait a moment and reload. If it persists for everyone, report it to support with the address and the time.

Common problems: a page is missing or empty

It is not published. The Pages tab shows Published, Draft or Empty for each page. Only Published pages are served. Open the page and use Publish draft.
It is for signed-in users only. Pages whose audience is Authenticated users only (tagged Signed-in) are left out of the menu for anonymous visitors.
The site has its own navigation. When the site's Navigation JSON (under Advanced (JSON): theme, navigation, settings on the General tab) has header items, it replaces the automatic page list. A live page that isn't listed there doesn't appear in the menu. Add it to the navigation, or check it by going to its path directly.

The authored navigation is shown as written. It does not check whether a page is published or who may see it. Remove links to unpublished pages, and links to signed-in-only pages if anonymous visitors shouldn't see them.

The page's audience is Authenticated users only, and the visitor is not signed in. After signing in as a member, they return to the page. This works only while Anonymous visitors is on. With it off, the visitor gets the 404 page instead (see above).

"This page is not available for your account."

The visitor is signed in, but the page still refused them, usually because their account is not a member of this portal. Check the portal's Members tab: the person should be listed with Login set to On. Details are in Portal pages and data views.

The page says "… has no published content yet."

The page has no published layout and no data view to list. Either:

the page was never given content, or was published while its draft was empty. Publishing an empty draft still marks the page Published. Add content, then Publish draft again; or
it is an Entity list page with no data view named in its embed target. Name the data view and save; or
it is an entity detail or app page embed. These types have no portal rendering of their own, so they show this message unless the page also has a designed layout.

A page that only embeds a data view shows Empty on the Pages tab even when it works, because the state looks only at the designed layout.

My change is not showing on the portal

The layout was saved but not published. Visitors see the page's last published layout. Use Publish draft. The Pages tab still reads Published after later edits, so it can't tell you that a draft is waiting.
You changed something that is live on save. The page's path, label, audience, embed target and SEO, the data view settings, and the site's label, description, switches, theme and navigation all apply as soon as you save. If those look wrong, the saved value is wrong.

Common problems: lists and data

A list shows "Data view failed (404)."

The list's data view could not be served. Check, in order:

The name in the embed target is wrong, or the data view was deleted. Setup doesn't display the data view's name, so see How do I find a data view's name?.
The data view is inactive. Deactivating a view stops serving at once. Reactivate it on the Data Views tab.
The site is not servable (see the first section). Data lists follow the same publish, Active and Anonymous visitors checks as pages.
The anonymous identity could not be set up. This applies to public views only. The server answers "Portal is not ready to serve data.", but the list still shows only the 404 text. The identity is normally set up on demand, and saving the portal on its General tab retries it. If saving does not help, contact support.

A list shows "Data view failed (401)."

The data view is for signed-in visitors only, and the visitor is not signed in. Put it on a signed-in-only page, or change the data view's audience to public if the data really is public.

A list shows "Data view failed (429)." or "Too many requests. Please wait a moment and try again."

The visitor made too many requests in a short time. Data views allow 120 requests a minute per visitor. The limit resets by itself.

A list shows no rows

The data view is serving, but the identity it runs as can read nothing that matches:

The entity view's filter matches nothing. Open the same view in the application and confirm it returns rows.
Record security excludes the rows. What you see as an internal user proves nothing. Public views run as the anonymous visitor identity under the Portal Anonymous profile. Signed-in-only views run as the signed-in visitor and show only what that account may read. The layers are explained in How portal security works.
A public view shows the same rows to a signed-in member. That is expected: public views always run as the anonymous identity, even for signed-in visitors. Use a signed-in-only view for "my records".

"No data view configured."

A data-list widget in a designed layout has no data view set. Open the page's layout, set the widget's data view, and Publish draft.

The visitor signed up but got no email

The address already had an account. Signup shows the same "Check your email" message either way, so it doesn't reveal which addresses are registered. No new email is sent, and the account is not added to this portal. Have the person sign in. If they need this portal, add them on the Members tab with Invite a contact.
The email is still on its way. The set-password invite is sent in the background after the account is created. Allow a few minutes and check the spam folder.
The person has not set a password yet. They can't sign in until they follow the link and set one.

"Self-registration is not available on this portal. Contact us for an invite."

Self-service signup is off on the portal's General tab, or the site is not published and active. Switch it on and save, or invite the person from the Members tab. The signup screen itself also needs Anonymous visitors on (see above).

"Too many attempts. Wait a few minutes and try again."

Signup allows 5 attempts per address in 10 minutes. Wait and try again.

"This account does not have access to this portal."

The account signed in correctly but is not a member of this portal. It may be a member of a different portal. Add the person on this portal's Members tab. When the contact already has a login, the toast reads "That contact already has a login: it now belongs to this portal too".

Check their Login column on the Members tab:

Invite held back — the login was created without sending the email. Use Turn on; the set-password email goes out now.
Invite sent — the login is on, but the person hasn't finished setting a password. Ask them to use the link in the email.
Off — the login was turned off. Use Turn on; they can sign in again.
On — the login is fine. Check that they use this portal's address and the email on record.

"This invite link has expired." or "This link has already been used."

An expired link needs a new invite. For a used link, the person should sign in, or reset their password from the sign-in screen.

"This account belongs to a partner portal and cannot use the tenant workspace APIs."

A portal account tried to use the internal application. Portal accounts work only on their portal. Send the person to the portal address. The other boundary messages are explained in How portal security works.

Example

A retailer reports that the Retailer Hub portal link "just says 404". The administrator opens Setup → Feature Hub → Portals → Portals. The row reads Published, Active, and Sign-in only under Anonymous. The retailer wasn't signed in, so the 404 is expected. The administrator checks the Members tab: the retailer's contact shows Invite held back. They click Turn on, and the toast reads "Login turned on". The retailer receives the set-password email, sets a password at the portal's /login address, and the portal opens.

Training

Practice exercise

In a sandbox, create a portal, add one page with a designed layout, publish the page and the site, and leave Anonymous visitors off.

Open the address in a private window. Expected result: the 404 page.
Switch Anonymous visitors on and save. Expected result: the page loads within a minute.
Edit the page's layout and save without publishing. Expected result: visitors still see the old layout until you use Publish draft.
Switch Active off and save. Expected result: the 404 page again, although Published still reads Published.

Quick reference

A portal tells visitors only "404". Find the reason in Setup.
Check in this order: address, Enable Portals, published, Active, Anonymous visitors, page, data view, identity.
New portals start with Anonymous visitors off. Visitors who are not signed in get 404, not a sign-in prompt.
Membership is per portal. Staff count as signed in everywhere, so test as a member.
Page layouts wait for Publish draft. Everything else is live on save.
Changed the slug of a published portal? Unpublish, then Publish.
"Data view failed (404)." means a wrong name, an inactive view or an unservable site.
An existing address gets "Check your email" at signup but no email and no membership.

Common questions

Why doesn't the portal tell visitors what is wrong?

Because anything more specific would leak information. If a portal said "this page exists but is for members", an outsider could map your hidden pages. So every gate that fails returns the same "not found". As the administrator, you have the full picture in Setup: the register row, the detail page header, the Pages, Data Views and Members tabs, and the module switch. Work through them in the order on this page and the cause shows up quickly.

The portal shows data we never meant to publish. Where do I look?

Check the Data Views tab of every portal, not just the one you were editing. All your portals share one anonymous visitor identity, so the public data views of all of them together decide what anonymous visitors can read. Deactivate any view that should not be public; it stops serving at once. Then review the Portal Anonymous profile for extra grants. Grants on other entities are not removed automatically. If the portal is also a storefront, review its catalogue separately. How portal security works walks through the full review.

I deleted a portal. Is its address and data still exposed?

Deleting a portal removes its pages and data views, and the address stops serving because the site no longer exists. Unpublishing is the safer first step, because it also removes the address registration at once. After deleting a portal that had public data views, check the Portal Anonymous profile and remove read access you no longer need, because deleting a portal does not withdraw the anonymous read grants its data views created.

Why can I see a page that my customer can't?

Your staff account counts as signed in on every portal, so it passes the members-only checks. Your customer is a member of one portal only, and only if their login is On. Always test with a member account in a private window.