Troubleshooting

Common issues when embedding Humind widgets, with the fastest checks for each.

Quick checks

Before digging deeper, run these:

1. document.querySelector('humind-widget') (or humind-quiz, humind-gift-finder, humind-product-questions): does it return the element?
2. Network tab: do the loader scripts (embed.thehumind.com/loader.js and/or widgets.thehumind.com/v1/loader.js) come back 200 OK?
3. Is your storefront domain whitelisted on the company in the Humind dashboard?
4. Console: any humind-* warnings or errors?

Most issues fall out of one of these four.

Nothing renders

Script didn't load

Open devtools → Network and look for either embed.thehumind.com/loader.js (chat) or widgets.thehumind.com/v1/loader.js (widgets bundle: quiz, gift-finder, product-questions). If the request is missing, your <script> tag isn't in the DOM or a CSP is blocking it.

Fix: ensure the tag is present on every page that renders a widget. For CSP, add:

script-src 'self' https://widgets.thehumind.com https://embed.thehumind.com;
connect-src 'self' https://api.thehumind.com wss://api.thehumind.com;
img-src 'self' data: https://*.thehumind.com https://cdn.shopify.com;
font-src 'self' https://embed.thehumind.com https://api.thehumind.com;

Bundle loaded, widget still invisible

Check:

document.querySelector('humind-widget')  // or humind-quiz, humind-gift-finder, humind-product-questions

If it returns null, your markup doesn't contain the custom element. If it returns the element but nothing is visible, look at the computed styles. A parent container with display: none, height: 0, or overflow: hidden will clip the widget.

My brand font isn't applied

You uploaded a font in the dashboard, the preview there looks right, but the widget on your storefront still shows the default typeface.

The font file is served from api.thehumind.com and, unlike images, a browser always fetches fonts in CORS mode. Two things block it:

1. A CSP without font-src. If your policy sets default-src 'self' and never declares font-src, the font falls back to that default and is refused. Add the font-src line from the block above.
2. A blocked or failed download. Open devtools → Network, filter on agents/fonts, and check the request returns 200 OK.

To confirm the font actually loaded, run this on your storefront:

[...document.fonts].filter(f => f.family === 'Humind Merchant Font')

An empty array means it never registered. Entries with status: "error" mean the file was fetched but the browser could not parse it, which usually means the uploaded file is damaged: re-export it as WOFF2 and upload again.

Note that the font is deliberately not applied in the playground on thehumind.com, only on your own domains.

Widget shows but backend can't resolve my product / collection ID

The widget mounts, but the backend responds 404/400 and the widget stays hidden or stuck on "Loading…".

Shopify merchants: products and collections are synced automatically. If an ID is missing, the initial sync may not be done yet (see Sync hasn't completed below).

Non-Shopify merchants: you must push the products and collections to the Humind backend yourself, and the externalIds you send must match the exact values you pass as product-id / collection-id on the widget. If they don't match, the backend can't resolve the widget and it stays hidden.

How to check: open the Network tab and look at the widget's resolution call, e.g.:

GET /widgets/product-questions?productId=<your-id>

• 200 with a payload → the backend found the product; the issue is elsewhere.
• 404 → the externalId you pushed doesn't match product-id.
• 400 → the ID format is wrong for the integration you declared.

Re-sync the affected products via your catalog push pipeline and re-check.

Widget loads but shows "Loading…" indefinitely

Identifier is wrong

Each widget needs a real ID in its platform:

• <humind-quiz collection-id="…">: Shopify collection handle or your internal collection ID.
• <humind-product-questions product-id="…">: Shopify GID (gid://shopify/Product/12345) or your internal product ID.
• <humind-gift-finder shop-domain="…">: the domain your Humind account is registered against.

Verify the request to api.thehumind.com/widgets/* in devtools. A 404 or 400 there tells you the ID is unknown.

Integration mismatch

If integration="shopify" but the ID you pass isn't a Shopify GID (or vice versa), the backend can't resolve it. Match the integration value to the ID format.

Sync hasn't completed

For a freshly installed Shopify store, give the initial sync a few minutes. Products appear in Humind within seconds of being published, but the first full catalog sync can take longer. Check app.thehumind.com → Catalog → Sync status.

Chat doesn't open when a widget chip is clicked

The widgets dispatch humind-open-chat on window. If the chat overlay (<humind-widget>) isn't on the page, nothing listens and the event is a no-op.

Fix: install <humind-widget> alongside the in-page widget. See Install the chat.

Chat opens but streams nothing

Two different streaming paths, two different failure modes:

• Chat overlay (<humind-widget>) uses WebSocket (wss://api.thehumind.com). If WebSocket is blocked, the overlay shows an "unavailable" state and never shows messages.
• Widgets bundle (quiz, gift-finder, product-questions) uses SSE via POST /chat/stream. If SSE is blocked, the quiz results (and other streamed content) load forever.

WebSocket blocked

Some corporate proxies and firewalls strip the Upgrade: websocket header. Check the Network tab → WS: you should see a long-lived connection to wss://api.thehumind.com. If it fails to upgrade or closes immediately, investigate the proxy or CDN between the browser and Humind.

Also make sure your CSP includes connect-src wss://api.thehumind.com.

SSE blocked

Some corporate proxies strip Content-Type: text/event-stream. Check the Network tab: you should see a long-lived POST to /chat/stream with partial JSON events. If it closes immediately or buffers the whole response, investigate your proxy or CDN.

Quiz looks wrong: my site's CSS is breaking it

<humind-quiz> is the only widget that uses light DOM. That means your global CSS cascades in and can override the quiz's own styles.

The chat overlay (<humind-widget>), <humind-gift-finder>, and <humind-product-questions> all use Shadow DOM, so nothing leaks in or out.

Workaround: scope your global resets, or wrap the quiz in a container that resets critical properties:

.humind-quiz-wrap * {
  box-sizing: border-box;
  /* any other resets you need */
}

Typical culprits: universal margin: 0, aggressive font-family overrides, line-height globals, and img { max-width: 100% } rules that collapse the quiz's product images.

For reference, the default font stacks are:

• Quiz (light DOM): system-ui, -apple-system, sans-serif
• Gift finder / Product questions (Shadow DOM): Arial, Helvetica, sans-serif
• Chat overlay (Shadow DOM): DM Sans

Hybrid Shopify setup (Shopify backend + custom storefront)

If you use Shopify for commerce but run your own storefront (headless, Hydrogen, or any framework serving from a non-Shopify domain), a few things differ from a standard Shopify install:

• Chat is not auto-injected. Shopify's theme extension only runs inside Shopify-rendered pages. On a custom storefront you have to paste the <humind-widget> markup and the embed.thehumind.com/loader.js script into your layout manually.
• CORS still applies. integration="shopify" tells the backend how to resolve products; it doesn't exempt your domain from the CORS whitelist. Add your custom storefront's domain to the company in the Humind dashboard.
• Add-to-cart won't work from the quiz. The quiz calls POST /cart/add.js at the same origin, which only exists on Shopify-hosted pages. On a custom storefront that endpoint returns 404. You'll need to listen for the quiz's product-selected event and call your own cart API.

Add-to-cart doesn't work from the quiz

Only happens on Shopify. The quiz calls POST /cart/add.js at the same origin as the page it's on. If you're testing against a shop from localhost, add-to-cart silently fails.

Fix: test on the actual Shopify preview URL, or use the Humind dashboard's playground.

Headless or hybrid Shopify: the quiz will not be able to add to cart automatically: cart.js isn't present on custom storefronts. You'll need to handle cart operations yourself by listening to the quiz's selection event and calling your own cart API.

humind-open-chat fires but the overlay ignores it

Confirm the event target is window, not document:

// ✅ Works
window.dispatchEvent(new CustomEvent('humind-open-chat', { detail: { message: 'Hi' } }))

// ❌ Won't trigger the chat
document.dispatchEvent(new CustomEvent('humind-open-chat', { detail: { message: 'Hi' } }))

<humind-widget> renders twice

The loader guards against double-registration but some bundlers (HMR in development, React strict mode) can trigger two scripts. <humind-widget> logs a console warning and skips the second registration; the other widgets (<humind-quiz>, <humind-gift-finder>, <humind-product-questions>) skip silently. If you see duplicate rendering in production, find the second <script> tag and remove it.

CORS errors on api.thehumind.com

api.thehumind.com allows:

• https://*.thehumind.com
• The merchant domain(s) registered on the company in the Humind dashboard

The whitelist is enforced backend-side, so a mismatch shows up as a CORS error in the browser even though the real gate is on the server. If you host under a domain we don't know about (a custom storefront, a staging subdomain, a white-label reseller domain), open the company settings in app.thehumind.com and add it, or contact support.

Language fallback

Setting language="xx" for an unsupported code falls back to English silently. To confirm which language is active, inspect the lang attribute on the widget's root element after mount.

Humind supports roughly a dozen language codes (English, French, Spanish, German, Italian, Portuguese, Dutch, and a handful of others). Unrecognized codes get English; they don't error. See Install the chat for the current supported list.

Still stuck?

1. Run document.querySelector('<element>').outerHTML and confirm the attributes are what you expect.
2. Grab a HAR file of the page load.
3. Email support with the HAR and the widget configuration. Include your company-id so we can look up the catalog state.