Troubleshooting

Common issues encountered when configuring or operating the platform, and what to do about them.

Symptom: The embed snippet is in the page but no chat launcher appears.

Things to check, in order:

The site's origin is on the deployment's Domains list. The widget actively refuses to render if the parent page's origin isn't allowed. Check the deployment's Basic Settings page: the scheme, host and port have to match — https://www.example.com does not cover http://www.example.com, nor a different subdomain. The path is not compared, so one entry covers every page on that site. For development, add http://localhost:3000 explicitly.
The script src is reachable from the visitor's browser. The embed snippet's src URL must resolve from wherever the page is loaded. A snippet pointing at http://localhost:3000 will not work on a public HTTPS site (mixed-content blocking) and won't be reachable by visitors outside your network anyway. Use the snippet from the deployment whose loader URL matches your production dashboard environment.
The browser console for errors. Mixed content, blocked third-party cookies, or CORS issues will surface there.
The deployment is actually saved. A new deployment has to be created (the Create Deployment button at the end of the wizard, not just the Next buttons). Until then the embed key isn't valid.

Symptom: The launcher appears, but opening it shows an empty or error page.

The widget enforces that it must be embedded inside an iframe. If you try to navigate directly to /widget/chat?deployment_key=... it refuses to render. This is a deliberate security gate.

If you need to preview the widget in isolation, use the dashboard's preview pane on the deployment's Content step (it renders the widget in a sandboxed iframe inside the dashboard).

Agent doesn't seem to be using my ingested content

Symptom: You uploaded documents in Ingesting knowledge but the agent's replies are generic and don't cite specifics.

Check the content's status. The Content list's Status column should read Ready. If it reads In progress, the pipeline hasn't finished — wait a minute and refresh. If it reads Failed, re-import it; if it fails again, contact support.
Check the chunks were created. Click into a content item and confirm the Chunks tab is populated. If the chunker produced zero chunks, the source content might be too thin or have parsing issues.
Check the retrieval is being triggered. In the playground, sources are shown beneath the agent's reply when retrieval ran. If the N sources chip is missing, the tool planner decided this turn didn't need a search — usually correct for greeting / acknowledgement turns. Ask a substantive question to force a search.
Check the question is one the knowledge base can answer. The skill that answers from your content is built in and always on — there is no toggle to check. If the agent is answering generically, the gap is in what was ingested, not in skill configuration.

A scan finds no pages

Symptom: You enter a website address in the import panel, press Find pages, and the Pages step reports that none were found.

Most common cause: the site has very few crawlable pages. Single-page sites find nothing, because the crawler reports pages reachable from the address you gave rather than that address itself. This is expected, not a failure.

For real multi-page sites that return 0:

Check Firecrawl can reach the site at all (some sites block scrapers).
Try without a trailing slash on the URL.
Check the site's robots.txt isn't blocking Firecrawl.

A scan finds pages, but not the ones I just published

Symptom: The Pages step lists pages, but one you added to your site recently isn't there — so it never gets imported and the agent doesn't know about it.

Before 11 August 2026, scanning read from a cached copy of your site's structure that could be up to seven days stale. Two scans of the same site days apart could return different page counts, silently dropping pages the site's own sitemap still listed. Every scan now does a fresh lookup, so this should no longer happen.

If you scanned a site before that date, open its pages and press Check for new pages — that adds whatever has appeared since, so anything missed at the time turns up and can be imported. If a page is still missing after that, check your site's own sitemap actually lists it and that it's reachable by following links from the address you gave.

A product exists in the knowledge base but Product Finder never recommends it

Symptom: The product page shows in the Content list as ready with chunks against it, but the agent doesn't surface the product when a visitor describes what it does.

Check the page has an overview chunk. Click into the content item and look at its chunks. Product Finder matches a visitor's description against the plain-prose overview of each product; a page whose chunks are all specifications, pricing, and tables has nothing for that match to land on. Re-import the page — the current chunker guarantees an overview on every product page, but pages ingested before 11 August 2026 may not have one. See How product pages are chunked.
Check the page classified as product. The Topic column on the Content list should read product. A page classified as knowledge or company isn't in the pool Product Finder searches at all.
Check the skill is enabled. Product Finder ships disabled and needs product attributes configured before it's useful — see Chapter 6.
Check a stated requirement isn't ruling it out. If the visitor has answered a mandatory attribute, the agent filters against it. A product whose page doesn't state that attribute may be excluded rather than ranked low. Try the same question in the playground without answering the narrowing question and see whether it appears.

Symptom: You expected the GDPR consent prompt to fire but it didn't.

The prompt fires under two conditions:

After four messages exchanged in the session, or
Immediately after the visitor submits personal data via a Book Meeting completion or Contact Request submission.

If neither condition has been met, the prompt won't appear. Send a few more messages or complete a booking / form to trigger it.

If you previously answered No in the same browser, that decision persists in localStorage and will suppress the prompt on subsequent sessions. Clear the widget's localStorage entry or use a different browser to start fresh.

Values persisted but a nudge didn't fire on a returning visitor

Symptom: A prospect comes back with property values already set, but a nudge that should fire based on those values doesn't.

This is a known limitation. Nudges evaluate against the current session's effective slot state — they don't automatically replay against persisted values on session start. The returning visitor's persisted values surface as context for the responder, but the nudge engine only re-fires once the conversation re-surfaces the relevant facts.

Workaround: design nudges whose criteria are likely to be re-surfaced naturally in conversation (e.g. current_challenge present will re-fire if the visitor mentions a new challenge on the next session).

Custom property added but skill doesn't see it

Symptom: You created a custom property, but a skill’s conversation inputs dropdown doesn’t show it.

The dropdown only lists enabled properties. New custom properties default to enabled, but if you've toggled one off (the switch on the property's row), it won't appear in skills until you toggle it back on and click Save toggles.

The booking calendar appears but bookings fail

Symptom: The booking calendar appears in the chat, the visitor picks a time, but Confirm booking fails.

Booking runs through your connected Cal.com account, not a pasted link. Check, in order:

The Cal.com card on Integrations still shows Connected. Reconnect required means the authorisation was revoked on Cal's side — reconnect it. Refresh failing usually clears on its own; if it persists for a day or two, reconnect.
The Book Meeting skill has an event type selected. A connected account with no event type chosen leaves the skill with nothing to book against.
The chosen event type is still published and active in Cal.com, and has availability on the calendar it's attached to.

If the skill's configuration shows "Connect Cal.com on the Integrations screen to choose an event type for this skill" instead of a dropdown, the account link is the problem — start there. See Chapter 11 — Integrations.

Email captured but classified into the wrong property

Symptom: The Properties tab on the prospect shows a value in the wrong field (e.g. "SaaS" in Job Title because the visitor said "we're a 60-person SaaS").

The slot extractor relies on each property's description to know what counts. Sharpen the description — "The prospect's individual job title — e.g. Head of Sales, CTO. Not the company's industry." gives the extractor a clearer signal. Captured values can't be edited on the prospect record, so the fix applies to conversations from then on.

Persistent misclassification across many prospects usually means the property description needs tightening.

Pipeline ingestion fails on certain documents

Symptom: A document upload stays In progress and eventually moves to Failed.

Check the file size. 4 MB per file is the upper limit.
Check your document-page allowance. An import refused because the allowance ran out ends as Failed. The Billing & Usage page shows what's left this cycle.
Check the format. PDF, DOCX, XLSX, PPTX, HTML, MD, RTF, TXT are supported. Other formats are rejected.
Re-upload. Occasional Unstructured.io API timeouts cause spurious failures; re-uploading often works.
Split the document. Very long, dense PDFs sometimes trip the parser. Split into smaller logical sections and re-upload.

HubSpot OAuth succeeds but no contacts sync

Symptom: You completed the HubSpot connect flow, the integration shows as Connected, but no contacts appear in HubSpot.

Generate some prospects. New prospects sync on creation; existing prospects (from before the integration was connected) don't backfill automatically.
Check the prospect shared contact details. A prospect is sent once the visitor submits a contact form or books a meeting — whichever way they answered the remember-me prompt, and whether or not they later used Manage data. That prompt governs the marker in their browser, not what reaches your CRM. An anonymous chat with no contact details has nothing to send.
Check the tile's status. On Integrations, Paused, Paused by plan or Reconnect required all mean the sync isn't running — see Reading an integration's status.
Check the OAuth grant scope. The platform requested the contacts and companies scopes — if your HubSpot admin restricted the grant to a subset, sync may partially fail.

Save is refused, or does nothing

Symptom: You press Save on a deployment, an agent, a team, a property, an attribute or a segment and it's refused — or, on a skill's conditions and nudges, nothing seems to happen.

A field is over its length limit. Limits are checked every time you save, so text written before they were enforced can block a save until it's shortened. Names are usually 50 characters and descriptions 200. On a deployment, Chat Title is 20 and Opening message 100 — and because switching a deployment Active or Inactive saves its whole configuration, an over-long field blocks that too. See Deployments & widget embed.
Another condition or nudge on the agent is broken. Saving a condition checks every condition on the agent, and saving a nudge checks every nudge. If one elsewhere can't be saved, nothing is written. See When a rule isn't behaving.
You're not an owner. Organisation settings, billing, and deleting the organisation are owner-only. See Organisation & team management.

The agent has stopped taking conversations

Symptom: A red notice across the top of every dashboard page says your agent has stopped taking new conversations, or stopped replying.

Your organisation has used its whole conversation or message allowance for this cycle. The agent resumes when the allowance resets — the date is on the Billing & Usage page — or straight away if an owner moves to a larger plan. If your trial has ended, the organisation is on the Free plan; choose a plan to start answering again. Nothing is deleted in either case. See Billing & usage.

Where to ask for help

If something behaves unexpectedly and isn't covered above, the platform team is the first port of call. Include in your report:

The team / project ID
The deployment / agent / prospect / session ID (visible in URLs)
The screenshot of the unexpected behaviour
What you expected vs. what you saw

Widget doesn't load on the website

Widget loads but stays inside its iframe parent — refuses to render content