Widget not loading

Six failure modes account for ~99% of “the launcher doesn’t appear” reports. Walk this diagnostic top-to-bottom; the first check that comes back red usually explains it.

Diagnostic

1. 1

   Is the loader script in the DOM?

   Open DevTools → Elements. Search (Cmd+F) for cdn.zubbyai.com. If it’s missing, the embed isn’t installed. Re-enable the Shopify App Embed or paste the universal snippet — see Embed codes.
2. 2

   Did the loader fetch?

   DevTools → Network → filter on zubby. You should see loader.js with HTTP 200 and a green status. If you see:

   • (blocked) — an ad blocker or browser extension killed it. Test in incognito.
   • 403 / 404 — the CDN URL is wrong or the loader version was deprecated. Use the embed snippet from the current dashboard.
   • net::ERR_BLOCKED_BY_CLIENT — adblocker again.
3. 3

   Did the bootstrap call succeed?

   Look for /api/v1/widget/bootstrap in the Network tab.

   • 200 — bootstrap worked. If the launcher still doesn’t appear, jump to step 6 (CSS).
   • 401 unauthenticated — widget key wrong or missing. Copy fresh from Dashboard → Widget → Embed.
   • 403 origin_not_allowed — your domain isn’t on the allowed-origins list. Add it under Widget → Allowed origins.
   • 429 rate_limited — extremely rare; means you’re hitting widget API limits. Talk to support.
   • 503 — Upstash / rate-limit infrastructure is degraded. Check the public status page.
4. 4

   Is the store ID right?

   From DevTools console run:

   js

   document.querySelector('script[src*="zubby"]').dataset.storeId
   // → should print your store ID

   Copy

   If the value is the wrong store (e.g. a staging tenant), update the embed.
5. 5

   Did Zubby.ready ever flip true?

   In the console:

   js

   window.Zubby?.ready  // true means it booted

   Copy

   If undefined or false, see steps 1-3.
6. 6

   Is something hiding the launcher?

   The widget renders inside a shadow root. Search Elements for [data-zubby-root]. If it exists but is invisible:

   • An aggressive display: none or visibility: hidden from a theme rule (rare).
   • The launcher is positioned off-screen — check Designer position settings, especially mobile offset.
   • Z-index conflict — bump the launcher z-index under Designer → Advanced if a theme overlay sits on top.

Shopify-specific

• App Embed isn’t toggled. Re-open the theme editor and make sure the toggle is on AND the theme is saved.
• Preview mode vs. live theme. The Shopify theme editor previews a copy of your theme. Make sure you’re editing the live theme, not a backup.
• Staff-only mode. If your store is in password- protected mode, the widget still loads but only for whitelisted staff IPs. Test on a guest device.

WooCommerce-specific

• Plugin deactivated. Confirm Zubby is in Plugins → Installed and active.
• Theme doesn’t call wp_footer(). Custom themes occasionally drop the call. Add it back, or paste the universal snippet manually.
• Caching layer. Object cache plugins (W3 Total Cache, WP Rocket) can serve stale HTML. Purge after install.

Still stuck

Email support@zubbyai.com with:

• A HAR file of a failed page load.
• Console errors.
• Your store ID and the storefront URL.

We usually have a fix back within a few hours.