Troubleshooting

A flat list of the most common problems and how to fix them.

The widget doesn't appear

1. Open the browser console. You're looking for [Zeeker] warnings.
2. Check window.zeeker exists. If not:
   • The loader didn't run. Is the <script> tag present in the rendered HTML?
   • Is the network request to loader.js or trigger.js reaching embed.zeeker.com? (Check the Network tab.)
   • Is a strict CSP blocking it? See Performance → CSP.
3. Check the async runtime. With loader.js, window.zeeker.getState() can return { loaded: false, pending: ... } before runtime.min.js becomes eligible; wait for the selected mode or call window.zeeker.load(). With trigger.js, only open() and close() exist before the configured host control is activated.
4. Check the config ID. data-zeeker-config="..." must match a published config. Drafts don't render.
5. Check the origin whitelist. If the config has Allowed origins set, the widget refuses to render on other hostnames.
6. Check anchor mode. If data-zeeker-mode="anchor", your page must contain <div data-zeeker-comments></div> or a data-zeeker-target="..." element.

[Zeeker] Missing data-zeeker-config

You included the loader without a config id. Add data-zeeker-config="..." to the script tag.

[Zeeker] Anchor mode: no container found

You set data-zeeker-mode="anchor" but neither data-zeeker-target nor data-zeeker-comments resolves to a DOM element. Add the container or change the mode.

SSO 400 Invalid signature

The JWT signature doesn't validate. Most common causes:

• Wrong HMAC secret on the server. Check .env.
• Wrong kid in the JWT header — must match the active key in the SSO config.
• Signed with the wrong algorithm (must be HS256).

SSO 400 Token expired

The exp claim is in the past, or further than 24 hours in the future. Mint short-lived tokens (1 hour is plenty).

SSO 400 Invalid audience

The JWT's aud claim is not embed.zeeker.com. Fix the claim.

SSO 400 Invalid configId

The embed config ID passed to /sso/exchange doesn't exist (or isn't a UUID). Re-copy from the configurator.

"SSO not enabled for this widget"

The embed's sign-in policy requests community SSO, but the parent community does not have an enabled SSO connection. Configure it in Admin Center → SSO, then return to the embed's Community → Login behavior settings.

Reply / reaction is rejected

• Rate limited? The widget enforces a per-user reply rate limit (default 30 / hour). The toast tells you so.
• Banned in the community? Bans are shown in the panel header with a reason.
• Locked thread? Mods locked the thread; reactions still work, replies don't.
• New account? Accounts under 24h old have a 5-minute cooldown between posts.

Wrong thread (SPA navigation)

SPAs that change window.location without a real navigation keep the original thread. Two fixes:

1. Call window.zeeker.refresh() on every route change.
2. Set data-zeeker-url="..." to a stable canonical URL.

Reply composer shows page context

An automatically linked page can have a hidden root card while its comments remain visible. Replying to that page shows Replying to this page, with the available page title or link as context. Replying to an individual comment shows that comment's own context instead. See Replies & threads.

Content stays in its original language

Embed language changes interface labels and layout. The current embedded Social experience does not translate member-authored posts or Chat messages. Choose the interface language under Appearance → Language in the Embed dashboard. See Embed language.

Article card shows only the URL or publisher name

1. Confirm the rendered article document includes og:title, og:description, and og:image. og:site_name is optional; the page title and icon have bounded fallbacks.
2. Inspect the values in the browser Elements panel, not only the original template. Client rendering, a consent manager, or an SEO plugin may have removed or replaced them.
3. Prefer an absolute HTTPS og:image. The loader resolves a relative HTTP(S) value against the article URL, but it rejects credential-bearing and non-HTTP(S) URLs.
4. Confirm the published Embed loader is mounted on that same page; it passes the browser-visible Open Graph fields during contextual boot.
5. Confirm the Embed's configured site URL has the same origin as the rendered article and the browser request. Host metadata is ignored when the configured site URL is blank or points at a different origin.
6. Reload once after publishing. Existing canonical roots are enriched on boot rather than duplicated.
7. Check whether a publisher resource/image restriction intentionally suppresses the preview. Restrictions remain authoritative even when the browser can read the tags.

Server extraction remains authoritative when it returned substantive metadata. Host-page values fill missing or generic fields; they do not overwrite a valid stored title, description, or image.

The panel or fixed Embed is blank

1. Confirm the outer loader and the inner Zeeker document both return 200, then inspect the iframe's console rather than only the host-page console.
2. Inspect the iframe document. If the document remains loading and <body> or #root has not been parsed, a render-blocking resource in <head> is stalled or blocked. Current Zeeker shells use their system-font fallback immediately and do not wait for Google Fonts to render; purge an old cached embed.html or app shell that still contains a blocking font stylesheet.
3. If #root exists but is empty, look for a failed JavaScript bundle, a runtime exception, or a blocked connect-src/frame-src request.
4. Clear a stale service worker/CDN response and reload the published configuration. Do not solve a blank current Embed by broadly weakening the host CSP; allow only the Zeeker origins listed under Iframes & sandboxed contexts.
5. If the frame loads only after a long delay, use the Network panel to identify the request holding document parsing. Third-party font, analytics, or publisher requests must not be on the Embed's critical boot path.

Launcher preview does not match Customize

1. Choose Desktop, Mobile, or Both before editing; Mobile has its own action order and bottom-tray setting.
2. In Element, enable or reorder actions in the action tray. The required Element opener cannot be disabled, and an action blocked by community or access policy shows its reason.
3. Expand Appearance & placement for size, color, and offset. The live launcher should update without saving.
4. Use the launcher/tray pencil to reopen the same controls. If a previously saved action list resets after a placement change, reload once and report the config ID; placement changes are expected to preserve authored desktop and mobile trays.

Widget looks "off" — wrong colors / font / radius

1. Published config? Confirm the embed is published and reload; boot data itself is fetched fresh.
2. CSS specificity? Your page might be setting --zk-accent (etc.) lower in the cascade than you think. Inspect the :root element in DevTools.
3. Saved theme? Explicit Light and Dark embeds intentionally ignore host theme changes. Choose Auto if the embed should follow the host.
4. Custom host theme signal? If Auto cannot infer a class-based theme switch, update the correctly named data-zeeker-theme="light|dark" attribute and reload/reinitialize the embed for that route.

Console: "Mixed content blocked"

The widget only loads over HTTPS. If your site is served over http://, browsers block the iframe. Move to HTTPS — there's no way around this.

"It worked yesterday and broke today"

Check the configurator → History — someone may have changed and published the config. Use Restore to roll back.

If the platform itself looks broken across multiple configs, contact support@zeeker.com so the team can check platform health.

Still stuck

Email support@zeeker.com with:

• Your config ID
• The URL where the widget should be running
• A console screenshot
• The browser + OS version

We respond within 1 business day during beta.