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;

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.

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.