Troubleshoot embedded help
The usual reasons the help panel stays empty, refuses to sign in, or opens the wrong topic.
The panel is blank, or the browser console says it refused to frame the page
The docs server does not list your page's origin in frame-ancestors, or your own
CSP blocks the frame.
Cause
Your app's origin is missing from OPEND_EMBED_ORIGINS, or is written with a
path or trailing slash.
Remedy
Add the exact origin, such as https://console.example.com, and restart the server.
Also allow the docs origin in your app's frame-src and
script-src.
Cause
Embedding is off: /embed/opend-help.js does not return the script.
Remedy
Set both OPEND_EMBED_SECRET and OPEND_EMBED_ORIGINS.
The panel says "Sign-in failed."
Condition
The token exchange at /embed/session answered 401.
Cause
The token is wrong: a different secret, an audience other than the docs site's
PUBLIC_URL (watch for a trailing slash), a lifetime over 600 seconds, a missing
iat, or an expired token because your server's clock is off.
Remedy
Decode the token and check each claim against Sign embed tokens in your backend. The server logs embed token rejected with the reason.
Cause
getToken rejected or returned something other than the bare token,
such as JSON.
Remedy
Return the token as plain text, or unwrap it in getToken.
The panel says "You do not have access to this help."
Condition
The token is valid, but the exchange answered 403.
Cause
The email is not registered as a reader, or is registered in a different organization from
the token's org.
Remedy
Register the reader in the right organization. The server logs embed token for unknown reader or wrong org.
The panel opens the wrong topic, or "No help here yet"
Condition
The context resolves differently from what you expected.
Cause
The route, the key or the reader's entitlements do not lead where you think.
Remedy
- Open the previewer's help lab, preview as a reader like the user, and try the same key or path.
- Check that the widget's
appmatches theappnamein the topics andhelp-contexts.yaml. - Remember that a hidden target falls back to the parent key or the default; see How a context resolves, and its fallback rules.
The panel asks for a token on every page
Condition
The session cookie does not stick.
Cause
The docs site is served over plain HTTP, so the browser drops the Secure
cookie, or the browser blocks partitioned third-party cookies.
Remedy
Serve the docs site over HTTPS. For browsers that block partitioned cookies, render help from the JSON API instead.