Troubleshooting

Docs / Troubleshooting

The problems that actually come up during a first installation, in the order you are likely to hit them.

Start Here

Most “it does not work” reports come down to one of four things. Check them in this order. It takes two minutes and usually settles it:

  1. Is the AI key valid?

    AI Chatbot → AI Providers → click Test next to the API key.

  2. Is the database schema created?

    AI Chatbot → RAG & Search → Check Status should say Schema is ready.

  3. Is the catalogue indexed?

    On the same screen, Total Products and Indexed should match.

  4. Is the license active?

    AI Chatbot → License & Updates should show a green License Active badge.

The Widget

The chat widget does not appear on the site

  • Check Appearance. The widget can be switched off entirely, or hidden on desktop or mobile on its own.
  • Check whether the current page is in the excluded-pages list.
  • Clear your caching plugin and CDN. A cached HTML page will keep serving the old markup without the widget.
  • Open the browser console (F12) and look for JavaScript errors from other plugins. One broken script can stop everything after it from running.

The widget appears but nothing happens when you send a message

Test the AI key first, on the AI Providers screen. If the test passes, open Logs and send another message; the failure gets recorded there.

The widget looks wrong on mobile

Check Appearance for the mobile-specific options, and clear the cache after any change, since the widget styling ships with the plugin assets.

AI Provider

“Test” fails on a key that you just created

  • Gemini: make sure the key was created in Google AI Studio recently, not reused from an old project. Older “standard” keys are being retired and stop working entirely in September 2026.
  • OpenAI: the account needs a payment method and credit before the API answers at all.
  • Check for stray spaces at the start or end of the pasted value.

Answers are slow

Switch to a faster model on the AI Providers screen. Check Logs for repeated retries or fallback switches, which double the response time.

The bot ignores your instructions

Put the instruction in Custom Rules (AI Providers screen). Rules outrank both the welcome message and the Context screen.

The bot invents products or details

That means it is answering without your catalogue. Work through the RAG section below: schema, indexing, and the key type.

RAG & Supabase

Indexing runs but nothing is stored

The wrong key. A publishable or legacy anon key can read but cannot write, so indexing silently produces nothing. Use the secret key (sb_secret_…) or the legacy service_role key. The RAG screen labels this field Service Role Key (not anon key).

Schema Status never becomes “Schema is ready”

  • Confirm you replaced [YOUR-PASSWORD] in the connection string with the real database password.
  • If the status says Manual setup required, your host blocks direct PostgreSQL connections. Use Copy SQL and run the script in the Supabase SQL Editor instead. The result is the same.

“Test Connection” fails

  • Check the Project URL for typos; it must include https://.
  • Free Supabase projects pause after long inactivity. Open the Supabase dashboard and resume the project.
  • Confirm your server can make outbound HTTPS connections.

The bot finds nothing after moving the site

Indexed data is tagged with the site’s domain, so several stores can share one Supabase project. After any domain change, staging to live included, run Re-index Products again.

Search quality dropped suddenly

If the embedding model was changed, old vectors are no longer comparable with new ones. Run a full re-index.

Customers cannot find products that clearly exist

Lower Similarity Threshold from 0.7 to about 0.6. If instead the bot returns loosely related items, raise it to 0.8.

License

The license will not activate

  • Check the key for stray spaces.
  • Each license covers a limited number of domains. If you moved sites, open the old site and click Deactivate License first.
  • Click Revalidate to force a fresh check.

The license shows the wrong domain

The license binds to the domain it was activated on. Deactivate it there, then activate again on the current domain.

Reading the Logs

Open AI Chatbot → Logs to see what happened on the last message: which provider was used, whether a fallback kicked in, whether a tool call ran, and any error the provider returned.

To capture more detail at the WordPress level, add this to wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Errors are then written to wp-content/debug.log. Turn it off again once the problem is solved; a debug log grows fast on a busy store.

Server Requirements

If behaviour is erratic rather than consistently broken, confirm the basics:

  • PHP 8.1 or newer
  • WooCommerce 8.0 or newer, active
  • PHP memory limit of at least 128MB, 256MB recommended
  • Outbound HTTPS allowed, so the site can reach the AI provider and Supabase
PreviousFAQ