Docs / Troubleshooting

Troubleshooting

Most issues come down to a key, a region, a missing image, or a not yet registered adapter. Here are the ones we see most often, with the exact place to look and the fix, in plain question and answer form.

The assistant replies with a generic "I cannot help right now" message

This is the graceful, branded fallback. When every configured provider fails, the assistant never shows a raw error or a dead end to the shopper. Instead it returns a friendly message and keeps the conversation open. The most common cause is an invalid or expired provider key.

To fix it, go to WooCommerce → Fahad AI, find your provider's key field (for example Anthropic API Key or your provider's key), and re-enter a valid key. The fields are masked password inputs, so paste the key fresh rather than editing the dots in place, then save.

Confirm the key belongs to the provider you selected. Anthropic (Claude) uses its native API; every other provider uses the OpenAI-compatible API.
Check the key has not been revoked or run out of credit on the provider's side. You pay the model provider directly, so billing problems show up here.
If you configured a second provider as a fallback, the assistant tries each one in catalogue order before degrading, so make sure every key you set is valid.

A branded fallback reply is by design, not a crash. It means the shopper stays looked after while you fix the key behind the scenes.

A streaming provider returns a blank reply

On streaming (server-sent events) providers, a transport error mid-stream is handled by graceful degradation: the assistant sends a friendly message and a clean end-of-stream rather than leaving the bubble empty. A persistently blank reply usually points at the model or the region.

Open WooCommerce → Fahad AI and check the model selected for your provider. A model id that your account cannot access for streaming will produce nothing useful. Pick a model your key is entitled to.
Check your account region with the provider. Some providers restrict certain models or streaming to specific regions, and a region mismatch can return an empty stream.
Confirm your server can hold an outbound streaming connection. Aggressive proxies, output buffering, or short timeouts can truncate the stream before any text arrives.

If a quick test still shows nothing, switch that provider's model to a known-good default and ask a simple question like "what do you have for under $50?" to confirm text is flowing again.

Product cards show a placeholder image instead of the real photo

The card image comes straight from the product's featured image. When a product has no featured image set, the assistant falls back to the standard WooCommerce placeholder rather than rendering a broken image. The card itself, with the title, price, and link, is still correct and live.

To replace the placeholder, set a featured image on the product:

Edit the product in Products, then set the Product image (the WooCommerce featured image) and update.
Bulk-check your catalogue for products with no featured image. Those are the ones that will show the placeholder in a card.

No setting controls this. The card mirrors the catalogue: give the product a featured image and the next card for it uses that image.

The wallet balance does not show for signed-in shoppers

Wallet and store-credit answers are intentionally decoupled from any one wallet plugin. The assistant ships the tools; your wallet plugin ships the data through a provider adapter. Two conditions must both be true for a balance to appear.

The wallet plugin must register an adapter on the fahad_ai_wallet_provider filter. Until something is registered, the wallet tools degrade to a graceful "not available" and never invent a balance.
The shopper must be signed in. Wallet operations are for logged-in customers only, and the assistant only ever reads the signed-in customer's own balance. Guests are blocked centrally before the tool runs.

If you maintain the wallet integration, register the adapter from your plugin like this:

add_filter( 'fahad_ai_wallet_provider', function () {
    return new My_WalletPro_Adapter();
} );

The adapter is an object (or an array of callables) exposing get_balance(), get_deposit_bonus(), top_up(), and pay_with_credit(). Any operation it cannot service should return an [ 'error' => string ] array rather than throw. See Wallet integration for the full contract.

If the adapter is registered and the shopper is signed in but the balance is still missing, check what your get_balance() returns. An error result is surfaced as "not available", never as a fabricated number.

The assistant returns a 429 response

A 429 with "Too many requests. Please wait a moment and try again." is the built-in per-client rate limit doing its job. The chat endpoints are public behind a nonce, so the rate limit caps how many billable AI calls and cart changes a single visitor can trigger.

It is a fixed window, keyed per client: logged-in users get a per-user bucket and guests are keyed by IP, so visitors behind a shared network are not lumped together. The defaults are 20 requests per 60 seconds.

If your store legitimately needs a higher ceiling or a different window, tune the two filters that drive it:

// Raise the per-client cap from the default 20 requests.
add_filter( 'fahad_ai_rate_limit', function () {
    return 40;
} );

// Change the window from the default 60 seconds.
add_filter( 'fahad_ai_rate_window', function () {
    return 30; // seconds
} );

Returning a limit of 0 or less disables the cap entirely, which we do not recommend on a public store since the rate limit is what protects you from a single visitor running up provider spend. See Hooks & filters for the full list of tunables.

← All docs Configuration →