Troubleshooting

This page lists the problems store owners run into most often, the exact message Geeky Bot shows for each, and what to do. Start with the health report: it catches most index and setup problems for you.

Where Geeky Bot reports problems

Geeky Bot checks its own setup and reports the result in two places:

Admin notice. When a check fails badly, the WordPress Dashboard and every Geeky Bot screen show Geeky Bot is answering from a degraded state. with a list of the problems. Only administrators see it.
Site Health. Open Tools → Site Health. The Geeky Bot search health test reads Geeky Bot search is healthy, Geeky Bot search needs attention (warnings only) or Geeky Bot search is degraded (at least one critical problem), with every failing check listed.

Health checks and what to do

The checks below are the ones Geeky Bot runs. Messages are shortened where they include numbers or table names.

Critical problems

Check	Message starts with	What to do
Database tables	“A Geeky Bot database table is missing” or “Geeky Bot database tables are missing”	Reload any admin page. Geeky Bot recreates missing tables on the next page load and then rebuilds the index. If the message stays, ask your host whether the database user is allowed to create tables.
Product search index	“The product search index is missing.”	Deactivate and reactivate Geeky Bot under Plugins.
Product search index	“The product search index covers the wrong columns”	Deactivate and reactivate Geeky Bot under Plugins.
Product search index	“The index looks correct but the last product search failed in the database”	The message ends with the database error. Send it to your host or to Geeky Bot support.
Indexed products	“None of your … published products are indexed”	Rebuild the index (see Products are not found).
Store policy answers	“Policy pages are selected but none are indexed”	Open Geeky Bot → Store Knowledge and select Refresh selected sources.
Assistant visibility	“WooCommerce is not active, so Geeky Bot cannot read your catalog.”	Activate WooCommerce.

While a product search index problem lasts, search still returns products, but with slower matching and no relevance ranking.

Warnings

Check	Message starts with	What to do
Indexed products	“Only … of … published products are indexed.”	Rebuild the index. A small gap is normal, so this shows only when more than 10% (and more than five) products are missing.
Store vocabulary	“No product categories have products in them”	Put your products in categories. Geeky Bot learns shopper words from them.
Store vocabulary	“Your product categories have not been read yet”	Geeky Bot starts learning them when it shows this. Check again in a few minutes, or rebuild the index.
Store policy answers	“No policy pages are selected”	Choose pages under Geeky Bot → Store Knowledge.
Store policy answers	“… of … selected policy pages are indexed.”	Select Refresh selected sources on Store Knowledge.
Assistant visibility	“The storefront assistant is switched off, so shoppers cannot see Geeky Bot.”	See The widget is not showing.

On a site whose database is SQLite, the Product search index check is always fine and explains that search uses simpler word matching. See Playground and SQLite.

Products are not found

Open Geeky Bot → Product Search.
In Test a phrase, type what the shopper typed and select Test search. You see the products Geeky Bot would show.
If nothing comes back, scroll to Tune the index and select Rebuild search index in the Product index card.
Wait for the notice. A small catalog finishes straight away: Product search index rebuilt. Indexed: … Skipped: … A large one carries on in the background, and shoppers keep using the current index until the new one is ready.
Test the phrase again.

If the text under the button stays at Full index scheduled or Full index pending, the background rebuild isn’t running. It uses WP-Cron, so check that WP-Cron works on your site. If DISABLE_WP_CRON is set in wp-config.php, a server cron job must call wp-cron.php.

If a product is still missing, check that shoppers can see it. Geeky Bot only shows products that are:

published (not draft, pending or private),
not password protected,
set to Catalog visibility: Shop and search results or Search results only in WooCommerce.

Products set to Shop only or Hidden are never shown. Variations are never shown on their own, only through their parent product.

Other things to check:

Product match behaviour on Product Search. Exact matches only hides close matches. A high Minimum score hides them too.
WooCommerce Coming soon mode. While the store is hidden, the chat is hidden from visitors. Administrators, shop managers and visitors with the private preview link still see it.

For how search ranks products, see How search works.

A product appears that shouldn’t

Edit the product in WooCommerce.
Set Catalog visibility to Hidden or Shop only, or change its status to draft or private.
Select Update. Saving a product updates the index, so the change applies straight away.

If shoppers see a product that only loosely matches their question, that is a close match. To show fewer of them, set Product match behaviour to Exact matches only or raise Minimum score on Product Search, then select Save search settings.

Developers can hide more products with the geekybot_product_visible_to_shopper filter. See Hooks.

A policy answer is missing

Geeky Bot answers policy questions only from published pages you have chosen.

Open Geeky Bot → Store Knowledge.
Under Choose public answer sources, tick the page that holds the answer.
Select Save and index pages.
Select Test a refund question, or ask the question on your storefront.

If the screen shows These selected pages are not recognized as policy sources and will not answer specific policy questions, Geeky Bot couldn’t tell from the page’s title and text what it covers. It recognises pages about shipping and delivery, returns, refunds, exchanges, warranty, cancellation, payment, privacy and terms. Give the page a title and wording that say which of these it covers.

Also check:

Shortcodes. Geeky Bot reads the page text as stored and doesn’t run shortcodes, so text that a shortcode or page builder adds isn’t read.
Out-of-date text. Pages refresh when you save on Store Knowledge. After an import or a page-builder migration, select Refresh selected sources.
The answer isn’t on the page. If the page doesn’t answer the question, Geeky Bot says it can’t confirm it rather than guess.

See Store Knowledge.

AI is not answering

When an AI call fails or isn’t allowed, Geeky Bot gives the shopper its local answer instead, built from your store data. Shoppers don’t see an error. The sign of a problem is answers that look like Local mode even though you chose Zywrap or OpenAI.

Some questions are always answered locally, even with AI switched on, so test with an open product or policy question.

Check the connection

Open Geeky Bot → AI & Privacy.
Under AI connection, check the selected answer mode and its status. Needs an API key or Needs an endpoint and key means the setup isn’t finished.
Paste the key again and select Save settings.

Check the AI limits

The Daily AI call budget (1,000 by default) and Monthly AI call cap (20,000 by default) apply to every AI call the site makes. Once one is reached, shoppers get local answers until the day or month ends. AI spend ceiling on AI & Privacy shows how many calls were used today and this month, and how many were declined. Raise the limit if you need to. See AI limits and costs.

Check for provider errors

If the provider refuses a call, the shopper gets the local answer. Smart Catalog shows the provider’s message on Product Search as Last attempt failed: … It retries automatically in 15 minutes. A failed Rescue call gives the shopper the normal no-results reply.

Zywrap replies to errors with these messages:

Status	Zywrap’s message	What to do
403	Invalid API key	Paste the key again, or connect your Zywrap account again on AI & Privacy.
402	Insufficient credits. Please top up your balance.	Top up in your Zywrap account. If you connected it from Geeky Bot, See balance and top up on AI & Privacy opens it.
429	You have exceeded the limit of 60 requests per minute. Please try again shortly.	Wait a minute. This limit applies to free and pay-as-you-go accounts.
429	Monthly free request limit exceeded.	Top up your Zywrap account.
500	An error occurred during your request.	Try again. Zywrap returns the credits for that call.

If Zywrap is down, Cloudflare answers with its own page (502, 521 or 524) and Geeky Bot uses local answers until Zywrap is back.

For OpenAI, check the key and its billing in your OpenAI account.

Your server must also be able to make outgoing HTTPS requests to api.zywrap.com or api.openai.com. If your host blocks them, every call fails.

See Zywrap and OpenAI.

Open Geeky Bot → Storefront Widget.
In Basics, turn on Show the assistant on my store.
Select Save widget.
Clear your page cache, your caching plugin’s cache and any CDN cache.
Open the storefront in a private window.

The chat is also hidden from visitors while WooCommerce Coming soon mode hides the store. You still see it as an administrator or shop manager.

“Security check failed” on a cached site

Each storefront page carries a WordPress security token (a REST nonce) created when the page was built. The chat sends it with every message. WordPress accepts a token for 12 to 24 hours.

On a site with full-page caching, a cached page can be older than that. Its token has expired, so Geeky Bot refuses the message with Security check failed. Please refresh the page and try again. In the chat, the shopper sees Your shopping session expired. Please refresh the page and try again. Refreshing doesn’t help while the cache keeps serving the same old page.

To fix it:

Clear the page cache.
In your caching plugin or CDN, set the cache lifetime for HTML pages to less than 12 hours.

Translations are not downloading

Geeky Bot downloads its translation from geekybot.com on sites that are not in English. Open Geeky Bot → Languages to see the status of each language and the reason for any failure.

Message	What to do
geekybot.com could not be reached (…)	Your server must be able to make outgoing HTTPS requests to `geekybot.com`. Ask your host.
The folder wp-content/languages/plugins is not writable.	Fix the folder permissions, or ask your host.
This site does not allow plugins to install language files (DISALLOW_FILE_MODS).	Download the `.po` and `.mo` files from Languages and upload them to `wp-content/languages/plugins/`.
The downloaded file did not match its checksum, so it was not installed.	Try again later.
Automatic installation is switched off on this site (GEEKYBOT_TRANSLATIONS_AUTO).	`GEEKYBOT_TRANSLATIONS_AUTO` is set to `false`. Select Install now or Update now on Languages. See Constants.

When an automatic install fails, the admin shows Geeky Bot could not install its … translation. with a Try again link. See Languages.

An API key isn’t saved

Geeky Bot stores OpenAI and Zywrap keys encrypted. If the server can’t encrypt, AI & Privacy shows API keys cannot be stored on this server. When you save, it shows The API key was not saved. Every other setting on the page is still saved.

Ask your host to enable the PHP Sodium (libsodium) or OpenSSL extension, then save the key again. Local mode works without either.

If AI & Privacy shows A provider key is still stored unencrypted., an earlier version saved the key. Enter it again and save to store it encrypted.

Commerce Pro licence problems

Open Geeky Bot → License to see the licence status and any message.

Message	What to do
That license key was not recognised. Check it against your purchase email.	Copy the key from your account on geekybot.com. Keys are five groups of five characters. If you updated from a version before 2.1.2, enter the key again: older keys came from the previous licence server.
This key is already used on as many sites as it allows.	Deactivate it on a site you no longer use, from that site’s License page or your account on geekybot.com.
This license has expired. Renew it on geekybot.com to activate a site.	Renew. On a site that was already activated, buying actions keep working, but updates, downloads, support and new activations need a renewal.
This license is on hold, usually a failed renewal payment.	Update the payment method in your geekybot.com account. Buying actions keep working meanwhile.
This license key has been replaced. The new key is in your account on geekybot.com.	Enter the new key.
This site needs a fresh license check.	Select Check my license again. This also applies after you move the store to a new address.
geekybot.com could not be reached, so Commerce Pro is running on its last confirmed check.	Nothing to do unless it lasts more than a few days. Commerce Pro keeps running for up to 30 days. Make sure the server can make outgoing HTTPS requests to `geekybot.com`.
This server cannot securely store the Commerce Pro license key.	Ask your host to enable the PHP OpenSSL or Sodium extension.
Geeky Bot Commerce Pro requires Geeky Bot core … or newer.	Update Geeky Bot first. Commerce Pro 2.1.2 needs Geeky Bot 2.1.2 or newer.
The downloaded Commerce Pro package did not match the release checksum.	Try again later. You can also download the zip from your geekybot.com account and upload it under Plugins → Add New → Upload Plugin.

If the admin shows Geeky Bot Commerce Pro is installed, but its features are locked until this site has a valid verified Commerce Pro entitlement., select Open license screen and activate the licence. See Commerce Pro overview.