Troubleshooting embedded components
Each entry below starts from what you see on the page.
Nothing renders
The element is in the DOM but empty, and the console warns that it was mounted without
init().
The module loaded and registered the elements, but init() has not run. Order does not
matter, so this is not a race: an element mounted first shows a skeleton and renders when the
configuration arrives. Check that init() is actually called, and that it did not throw.
init() threw.
It throws synchronously when deploymentUrl, tenantId, serverId, or tokenProvider is
missing, so that the mistake surfaces at your call site. Read the message.
The import failed.
Check script-src in your Content Security Policy, and that the URL matches your deployment.
The entry point is /embed/v1/embed.js.
The console warns that an element is already defined by another copy of embed.js.
The page loaded the module twice from different URLs: two deployments, or one deployment with a
different query string or host spelling. The browser keeps the elements from the first copy, and
only that copy's init() configures them. Load the module from one deployment, at one URL, per
page.
The tag renders as an unknown element and nothing happens.
The module never loaded. In a bundled application this is usually the bundler resolving the
absolute URL in import() at build time. See
TypeScript and frameworks.
It loads, then fails
An error banner appears after the element has rendered. Usually a scope the client was never granted. Open the client's Embed tab: anything missing is marked there, and one click grants the set. The elements read the person's data with their token, so a scope the client cannot request is one the token cannot carry.
A pane renders, but one section of it is empty and there is no error.
Two things are hidden rather than bannered. The profile sections disappear for a user whose
profile is managed outside SecureAuth, which is a property of that user and not of the client.
The last sign-in row disappears when the client cannot read sessions: check the Embed tab
for a missing view_sessions, grant it, and reload. A missing scope anywhere else raises the
banner above instead, so silence here means the content is genuinely not available.
The error cannot be dismissed. That is a gating error: the element cannot render at all, usually a missing required attribute or a subject that does not exist. Fix the attribute and the element recovers on its own, without a remount.
It works, then stops after a while.
The token expired and tokenProvider handed back the same one. The element calls it again
after a 401 and retries once, so that call has to return a renewed token. A getToken() that
returns a cached value turns this into a loop. See
Authentication and tokens.
Every element on the page failed at once.
There is one tokenProvider per page, so an expired session reaches all of them together.
That is the symptom of a session problem, not of one element. Sign the person in again: the
first request that succeeds with the new token clears the error on every element. An element
you mount afterwards makes its own requests before reporting anything.
It looks wrong
Unstyled content under a strict policy.
The elements inject their styles at runtime and need a nonce. Pass styleNonce to init(),
or put <meta property="csp-nonce"> in the host page's head. See
Security and CSP.
A few pixels tall, or no taller than its content.
The container has no definite height. A percentage height resolves against the parent's
computed height, and min-height does not make auto definite. Give the container a height,
or lay it out with flex or grid.
Two scrollbars. A fixed-height container inside a scrolling page. Pick one: constrain the container and let the element scroll its own content, or let the container grow and let the page scroll.
The font is not the one the variant set.
The font URL has to point to a font file (WOFF, WOFF2, or TTF), not a stylesheet. Check font-src
in your policy as well.
A color was ignored.
Colors must be 3, 4, 6, or 8 digit hex. Names such as blue and functions such as rgb() are
ignored, and a value left out keeps the base theme's rather than resetting to a default.
Tenant branding did not apply in dark mode.
It does not. That branding is authored against the light theme and carries no dark variant, so
under mode: "dark" nothing is fetched or applied. Use theme.style, which has values per
mode.
It renders the wrong thing
A pane shows nothing at all. Its variant hides every section it has. The admin console warns about this combination on the Embed tab, because an element that mounts and renders nothing reads as a bug in your page.
A tab is missing from the composite. Its tab is switched off in the variant, which also makes that route unreachable. The same pane mounted directly still renders.
A section is hidden but its request still happens.
Expected when something else visible needs the same data. Hiding sessions drops the MFA
request immediately, while the sessions request continues as long as the identity header is
still showing a last sign-in row.
Changes in the admin console did not reach the page.
The configuration is read when init() runs. Reload the host page.
Code changes look like they did nothing.
Values passed to init() win over the variant, so a sections or theme block left in your
page overrides what an administrator changes in the console. This is what Manual overrides
on the Embed tab adds, and the reason to leave it off unless you need it.
Setting up a passkey fails
A passkey is bound to the origins it may be used on. By default that is the SecureAuth deployment's origin, not your page, so registering a passkey from an element fails until the identity pool allows your page. In the pool's passkey settings, set Relying Party ID to a domain your page is on and add your page's origin to Relying Party Origins. See Passkeys.
If the element asks the person to sign in again first, that is the recent sign-in check. See Recent sign-in for sensitive changes.
The Embed tab is missing
The tab is on every client that can carry a user's access token, so check the client first: a SAML registration and a machine-to-machine client never show it, because neither has a signed-in person whose data an element could render. Give the client a user-facing application type (for example Server web or Single page), and the tab appears.
If Embedded components is also missing from the Extensions section of the navigation,
that is a permission, not the client: your administrator role needs read_embed_variants on
the workspace.