Troubleshooting overview
Production issues with Zubby almost always fall into one of eight buckets. This page is a triage table — pick the symptom, jump to the fix. Two of the harder fixes have dedicated deep-dive pages linked at the end.
Triage by symptom
| Symptom | Most likely cause | Fix |
|---|---|---|
| Widget doesn’t appear on storefront. | Embed missing, key wrong, origin not allowed. | See Widget not loading. |
| Widget appears but says “unavailable”. | AI provider key not configured, or worker not running. | Verify provider key under Admin → Providers. |
| WooCommerce plugin crashes WordPress. | PHP version below 7.4 or memory limit too low. | Upgrade PHP to 8.x, increase WP memory limit to 256M. |
| Catalog sync stuck at 0%. | WooCommerce REST permissions revoked, or Shopify webhook missed. | Re-pair (Woo) or click Resync (Shopify). |
| Embedding bar stuck at 0%. | Embedding worker not running, or provider quota exceeded. | See Embedding worker / DLQ. |
| OpenAI 401 / quota errors. | Key expired, hit org quota, or wrong project. | Rotate the key in Admin → Providers → OpenAI. Failover to Anthropic/Azure if you have them. |
| Recovery emails not sending. | DKIM/SPF misconfigured, sender pool deferred, or hard-bounce suppression. | Recovery → Domain shows DNS health. Hard bounces suppress per shopper for 90 days; check suppression list. |
| Conversations are slow to reply. | Provider latency, or large catalog with cold cache. | Switch primary provider under Admin → Providers. Slow first replies after deploy are normal — they warm up. |
If you can’t reproduce
Open
Settings → Status for a live read of every Zubby subsystem. Many issues are upstream incidents we’ve already noticed.Self-serve health checks
Quick checks to run before opening a ticket:
- Public status page — /status for live availability and any ongoing incidents.
- Sync status —
Dashboard → Catalog → Syncshould be green and current. - Worker heartbeat —
Settings → Status → Workershows the last heartbeat. If it’s more than 60 seconds stale, the BullMQ worker isn’t processing jobs. - Provider health —
Admin → Providersshows latency p95 + error rate per provider per capability. - Webhook deliveries —
Settings → Webhooks → Deliveriesfor inbound and outbound flows.
Common gotchas
- Cookie-blocking browsers (Brave default, Safari ITP) can break the visitor cookie. The widget still works but loses cross-session continuity for that shopper.
- Ad blockers sometimes block the loader script. Test on a clean profile if the launcher doesn’t appear for one teammate but works elsewhere.
- Shopify “Online Store 2.0” vs. “Vintage” — the theme App Embed only works on 2.0. Use the universal snippet for older themes.
- WooCommerce REST API permissions can be revoked by security plugins (WordFence, Sucuri). Whitelist Zubby or disable “lockdown” mode during initial sync.
- Multi-region setups — if you migrated workspace regions, old API keys / widget keys won’t work in the new region. Rotate them.
When to email support
If a self-serve fix isn’t obvious within 10 minutes, email support@zubbyai.com with:
- Your store ID.
- The URL of the page you’re seeing the issue on.
- Browser DevTools network log (HAR) if the issue is client-side.
- The time the issue started, in your time zone.
First response within 4 business hours on Growth; within 1 business hour on Pro; 24/7 within 15 minutes on Enterprise.
Deeper dives
- Widget not loading — step-by-step diagnostic.
- Embedding worker / DLQ — when products never become searchable.