Troubleshooting

Only problems the implementation actually handles or that follow from it.

AI response not working

Possible cause No key, invalid key, budget spent, Enable AI Agent off, provider timeout.

Solution Test API Key on AI Provider. Check Usage & Costs budget. Confirm Enable AI Agent. Read WooCommerce logs source aiwsa. Catalog search should still work without AI.

API key invalid

Possible cause Wrong secret, constant vs saved key mismatch, host blocked from api.openai.com / Google.

Solution Retype key or set AIWSA_OPENAI_API_KEY / AIWSA_GEMINI_API_KEY. Test API Key. Ensure sslverify can succeed (do not disable TLS).

Product search returns no results

Possible cause Product not published/visible; search tool off; overly strict category guess (mitigated in current code); out-of-stock hidden; empty catalog.

Solution Search the exact title in chat. Confirm publish + catalog visibility. Enable Fallback to WooCommerce search. Enable Include out-of-stock if you expect those rows. Untyped simple products and missing stock meta are included by Catalog_Query.

Product recommendations unavailable

Possible cause rec_enabled off; recommend_products off; REST 404 on /recommendations; no linked products and no catalog matches.

Solution Enable Recommendations settings and tool. Fill WooCommerce Linked Products. Flush permalinks if REST 404. Chat still works if that GET fails (JS swallows the error).

Language detection issue

Possible cause Fixed language override; custom Appearance welcome; unsupported language; Remember off.

Solution Use Auto Detect or the correct fixed code. Clear custom Welcome Message to use fallback welcomes. Stay on the 11 allow-listed languages.

Add-to-cart not working

Possible cause add_to_cart off; not purchasable; variation not selected; confirmation expired; nonce stale; rate limit.

Solution Enable cart tools. Confirm the dialog. Reload so /config issues a new nonce. Check stock. Do not expect the client to set prices.

Chatbot not appearing

Possible cause Enable AI Agent off; floating launcher off; page already has shortcode; cached HTML from before install; JS error; not a storefront request.

Solution Turn agent on, launcher on, or add shortcode. Purge cache. Check browser console for widget.js. Visit a shop page logged out.

Frontend JavaScript error

Possible cause Theme/plugin conflict; REST root wrong; blocked cookie.

Solution Disable other chat widgets. Confirm aiwsaBoot.restRoot points at /wp-json/aiwsa/v1. Guests need the config nonce, not a key.

WooCommerce compatibility issue

Possible cause WooCommerce inactive; version below 8.2; HPOS confusion.

Solution Activate WooCommerce 8.2+. Plugin declares HPOS and cart/checkout blocks compatibility. Orders use wc_get_order().

REST API issue (404)

Possible cause Pretty permalinks off / rewrite rules stale; plugin not loaded; security plugin blocking aiwsa/v1; wrong restRoot.

Solution Settings → Permalinks → Save. Confirm routes under /wp-json/aiwsa/v1/config. 404 is “route not found”, not a nonce failure (that would be 403/401).

Permission issue

Possible cause Shop manager cannot see API keys; shopper REST without nonce; confirming another visitor’s conversation.

Solution Keys need manage_options. Widget must call /config first. Conversations are ownership-token scoped.

Recovery emails not sending

Possible cause Feature off; no consent; no email on cart; WP-Cron; wp_mail failure.

Solution See Cart recovery. Send test email from Cart Recovery settings.

Streaming not streaming

Possible cause Transport set to SSE but bundled widget uses POST.

Solution Expected in this version. Leave Transport on Blocking request.