Troubleshooting
Find your symptom. Each row says what is actually happening and what to change.
The widget does not appear
Check your live site in a private window first — a logged-in session, an ad blocker or a stale tab accounts for a good share of these.
| Symptom | What is happening | What to do |
|---|---|---|
| Nothing at all, on every page | The snippet is not in the HTML the browser received — usually because it was pasted somewhere that does not render on the live site. | View the page source (Ctrl-U) and search for helpbrain. If it is not there, the paste did not take: re-check you used the site-wide footer or layout template, not a single page's content. |
| Nothing, and you use Webflow or Framer | Custom code only goes live when the site is published. Saving is not publishing, and it never runs in the editor preview. | Publish the site, then check the published URL rather than the preview. |
| Nothing, and the source does contain the snippet | A Content-Security-Policy header is blocking the script before it runs. The browser console will say so explicitly. | Add https://helpbrain.net to your script-src and frame-src directives. See the install guide's content security policy section. |
| It appears on one page only | The snippet landed in that page's content rather than in the shared template. | Move it to the footer or layout template that every page renders. |
| It appeared, then stopped after a WordPress update | A theme update overwrote footer.php, taking your snippet with it. | Re-add it through the WPCode plugin instead, or use a child theme. Plugin snippets survive theme updates. |
| The bubble is there, but clicking it opens nothing | The script loaded but the conversation frame is blocked — almost always frame-src in your CSP, since the chat itself runs in an iframe. | Add https://helpbrain.net to frame-src as well as script-src. |
| Old visitors see it, you do not | A page cache or CDN is still serving the version of the HTML from before you pasted the snippet. | Purge the cache, or wait for it to expire — usually a minute or two. |
Note
The installation check in your dashboard fetches your homepage from our side. If it says it could not reach the page, that is a different problem from a missing snippet — your firewall or WAF is blocking us, and the snippet may be perfectly fine.
The bot will not answer, or answers badly
Almost every case here is a content problem rather than a model problem. The bot answers from your pages and refuses to invent anything that is not on one, which means an unanswerable question is telling you something true about your content.
| Symptom | What is happening | What to do |
|---|---|---|
| It says it is not sure and offers a person | The confidence gate. Nothing it retrieved supported an answer, so it escalated rather than guessing. | Check the question is actually covered by a page you have added. If it is not, add the content — or answer once from your inbox and it will be used from then on. |
| It is not sure about something that IS on your site | That page was probably never read: it may be excluded, unreachable, blocked in robots.txt, or behind a login. | Open your sources and look for the URL. If it is not listed, add it directly as a page source; if it is listed as failed, the reason is shown beside it. |
| The answer is out of date | Your site changed since the last crawl. The nightly re-crawl runs at 05:00 UTC. | Re-sync the source by hand from the sources page rather than waiting for tonight. |
| The answer is confidently wrong | It found a page that looked relevant and was not — often an old page you forgot was still published. | File a correction, which is remembered for that question. If the page itself is the problem, remove that one page from the source and its content stops being used. |
| It answers in the wrong language | The bot replies in the language the visitor wrote in. The widget takes its interface language from your page's html lang attribute. | Check that attribute is set correctly on your site. It has no effect on which language answers come back in, only on the widget's own labels. |
Tip
A question the bot could not answer is not lost. It goes to your inbox, and answering it there teaches the bot for every future visitor.
A page never got read
Each failed URL carries its reason. These are the ones worth knowing about:
| Symptom | What is happening | What to do |
|---|---|---|
| Blocked | Your host refused us — most often Cloudflare's AI-bot blocking, or a WAF rule matching a datacentre IP. | Allow our crawler by its user agent, HelpBrainBot. Our crawler page has the exact string and a description of how it behaves. |
| Not found / server error | The URL 404s or 500s for us, exactly as it would for anyone else. | Open the URL yourself in a private window. If it works for you but not for us, it is access control rather than the page. |
| Empty | The page loaded but had no readable text — usually an app shell that renders its content in JavaScript we could not run. | We retry with a real browser automatically. If it still comes back empty, add the content as a file or as pasted text. |
| Too large | The file is over 25 MB, the same ceiling an upload has. | Split it, or upload the section that actually answers questions. |
| A linked PDF was skipped | Scanned PDFs need a multimodal read, and a single sync will only pay for a limited number of them. | Upload the important ones directly as file sources, where they are not competing with the rest of the crawl. |
| Some pages stopped being read entirely | You have reached your plan's page limit, which counts URLs across every bot in the account. | Remove sources you do not need, or move up a plan. Plans and limits explains exactly what counts as a page. |
Still stuck
These pages go deeper on the mechanisms above: