Troubleshooting overview
Production issues with Zubby almost always fall into one of a few common 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”. | A Zubby service is degraded or the store setup is incomplete. | Check support, then review the store’s Store Details and Notifications. Contact support with the store ID, affected URL and timestamp if the issue continues. |
| WooCommerce plugin crashes WordPress. | Version incompatibility, a plugin conflict, or a PHP error. | Check the installed plugin’s declared requirements and the PHP error log. Reproduce in staging and isolate the failing plugin or theme before changing production settings. |
| Catalog sync stuck at 0%. | Woo plugin never finished pairing, or Shopify sync job failed. | Re-run Log in & Connect from the plugin (Woo) or click Sync now on Catalog → Products (Shopify). |
| Products are present but not becoming searchable. | Sync or search indexing has not completed. | See Products not becoming searchable. |
| Custom store has no products. | No write-scoped key was used, the payload failed validation, or the source system has not pushed the catalog. | Check every item in the API response's errors array, then follow the custom integration guide. |
| AI replies or indexing show a service error. | An AI service may be temporarily unavailable. | Check support and Notifications. If the error persists, contact support with the affected feature, store ID, and timestamp. |
| Recovery emails not sending. | Mailbox disconnected, service delay, or shopper ineligible or unsubscribed. | Check your email-sending connection under Integrations (re-consent if the mailbox token expired), confirm the shopper is eligible, and retry one controlled send. If it remains pending, contact support. |
| Conversations are slow to reply. | Provider latency, or large catalog with cold cache. | Check the affected conversation, Store Details and Notifications. AI provider credentials are managed by Zubby, not in merchant settings. If replies stay slow, contact support. |
If you cannot reproduce the issue
Contact support with the time of the issue, the affected feature and steps to reproduce it. Never include passwords or access tokens.
Self-serve health checks
Quick checks to run before opening a ticket:
- Support - contact our team if you cannot access your store or dashboard.
- Sync status -
Catalog → Productsshould show a recent successful sync and a product count that matches your store. - Store activity - open Store Details and review recent sync or job status for the affected store.
- Notifications - look for failed sync, indexing, delivery, billing, or connection alerts that explain the merchant action required.
- Connector health - the
Integrationspage shows each connection’s state; the WooCommerce plugin also reports webhook health on its settings screen.
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 app embed compatibility - Shopify supports app embed blocks in both vintage and Online Store 2.0 themes. This does not establish that every theme has been tested with Zubby. Existing connected stores should verify the embed on their theme before publishing; new Shopify connections are coming soon. Use one installation method at a time to avoid duplicate loaders.
- WooCommerce REST API permissions can be revoked by security plugins (WordFence, Sucuri). Identify the blocked endpoint and response in the security log, then add a narrowly scoped allow rule where appropriate. Keep unrelated protections enabled.
- Stale embed snippets - if you rotated your widget key, any hard-coded snippet keeps the old key and gets 401s. The per-store loader tag picks up the new key automatically; re-copy it from the dashboard if you inlined anything.
When to email support
If the checks above do not isolate the problem, email hello@zubbyai.com with:
- Your store ID.
- The URL of the page you’re seeing the issue on.
- A sanitized browser network log if needed: remove cookies, Authorization headers, tokens, request bodies with personal data, and private response content before sharing a HAR.
- The time the issue started, in your time zone.
Response time depends on request scope and current support capacity. No plan-specific public response-time SLA is promised in these docs; contractual commitments must appear in an executed agreement.
Deeper dives
- Widget not loading - step-by-step diagnostic.
- Products not becoming searchable - merchant checks for sync and search-indexing delays.