Help
Symptom, check, fix. Start with the plugin’s own health screen — it is faster than this page and it names the stage that failed.
The widget doesn’t appear at all
Check Display Location under AnswerRails → Chat Settings → Basic Setup: home page only, all pages, a list of pages you choose, or shortcode only. If it is set to the custom list, the picker sits directly beneath the drop-down — confirm the page you are looking at is ticked in it. Then purge your caching plugin: a cached copy of the page from before you enabled the widget will not have it.
The widget says chat is disabled
Either Enable Chat Widget under Chat Settings → Basic Setup is off, or no API key is set for your active provider. The Overview says which. Add a key under Chat Settings → AI Provider, pick a model, save, and run Test APIs.
Answers stop coming
Run Test APIs and read what it says. Each state means something specific:
- Please configure your API key in Settings. No key is set for your active provider.
- Chat is currently disabled. The Enable Chat Widget switch is off.
- Credentials error. The key is present but rejected: wrong, revoked, or belonging to a different account. Re-paste it.
- Quota or billing error. Your provider account is out of credit or over a limit. Top it up or check the provider’s own dashboard — usage is billed to your provider account, not to AnswerRails.
- Vendor busy, or a temporary error. The provider is rate-limiting or having a wobble. It usually clears on its own; the visitor sees a retry message rather than a wrong answer, and where the provider offers a second endpoint the plugin fails over automatically.
- Moderation unavailable. Every visitor message is checked before it is answered. If that check cannot run, the assistant fails closed and asks the visitor to try again rather than skipping it.
- Rate limited. That visitor’s session has sent too many messages in five minutes. This is per-session protection and it clears on its own.
- Model retirement notice. The provider is retiring your configured model. Choose the suggested replacement under Chat Settings.
Sync isn’t working, or an item won’t sync
Bulk sync reports each item’s outcome — how many synced and how many failed — and does not report success over a failure, so read the count rather than the colour. An item that failed keeps a Sync failed mark until it succeeds, which is how you tell “never tried” from “tried and failed”. Last Synced is the server’s answer, not the browser’s.
One cause worth ruling out early when a whole batch fails is the plugin’s temporary folder under wp-content/uploads/answerrails-temp not being writable by the user PHP runs as. The Knowledge page warns you when it is not writable; fixing the ownership or permissions of that folder on the server fixes the sync. If items still fail after that, your server’s PHP error log will name the reason, and Test APIs will tell you whether the knowledge-search service itself is reachable.
Two other states are not failures. Sync frozen means that item’s source type is not registered on this installation, so it is no longer refreshed; it carries on being served as last synced. Source unavailable means the page it came from has gone: its last good copy keeps answering for 24 hours, and it is then withdrawn from answers until the source returns.
A long conversation stops, or a long message will not send
Every message carries the conversation so far to your site, and anything in front of the site — a firewall, a CDN, a security plugin — can refuse a request it considers too large. The assistant keeps each request within a fixed size by sending the model only the most recent turns that fit. The visitor still sees the whole transcript, and it survives a reload, but on a very long conversation the assistant will not recall the earliest turns.
If a request is refused anyway, the visitor is told the message could not be sent and pointed at the new-conversation button, which starts afresh. A single message that is too long is held in the message box with a note asking for it to be shortened, and the text stays put. If your hosting allows larger requests, the answerrails_history_byte_budget filter raises or removes the limit.
It declines a question your pages cover
If Test APIs is green and the assistant still says it doesn’t know, that is usually the product working: it answers only from your knowledge base and says so when your content does not hold the answer. Three things to try, in order.
Ask again, or rephrase.
Retrieval matches the words in the question against the words in your content. A question phrased the way a visitor would put it can miss a page that answers it in different language.
Look at Chat Logs.
The log shows which path through the pipeline produced the reply, which separates “nothing was retrieved” from “something was retrieved and judged irrelevant”.
Add or improve the content, then re-sync.
If the answer genuinely is not on a page, add one. If it is, consider whether that page says it in the words a visitor would use. On a very small knowledge base the local keyword index scores everything near zero, so add several items before judging it.
If your knowledge base is large and the local keyword index keeps missing, vector search matches on meaning rather than keywords and usually answers more accurately — see the operator guide. To compare, set Retrieval to Local keyword only and ask the same question again.
The Sources block looks wrong
Sources are computed by the plugin from what retrieval actually returned, never written by the model. Where the plugin cannot judge which of several candidates the answer really used, it names its single best candidate rather than listing several it cannot vouch for. Sources that are knowledge-base items with nowhere to click render muted and italic, and are announced as a reference to screen readers, so you can tell at a glance which sources open and which do not.
Escalation emails are not arriving (Pro)
When a notification email cannot be sent, a notice on the AnswerRails admin screens says how many have failed and when the most recent failure was, and the visitor is told the request did not reach your team. The escalation settings are not the cause: email leaves through whatever mail route your WordPress site already uses, so look wherever your site’s other email comes from — your host’s mail service or your mail plugin. A quick check is whether WordPress can send you anything at all, such as a password reset. Test APIs does not cover mail; it tests your chat provider, knowledge search and moderation.
Still stuck
Email support@answerrails.com. A person reads it and a person replies. Include:
- What Test APIs reported, in its own words.
- Your AnswerRails version and your WordPress version.
- Which provider and model you are using.
- What you expected and what happened instead. Screenshots help more than descriptions.
You can also ask the assistant on this site — it is grounded in these pages, cites what it used, and says so when the answer isn’t in them. If your question should have had a page here, tell us and we will write it. Support has the full detail, including how to report accessibility problems and security issues.
