Appendix B — 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 and confirm the URL matches exactly — including the protocol (https:// vs. http://) and the path if you've been specific. For development, add 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 Chapter 4 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's stuck at processing, the pipeline hasn't finished — wait a minute and refresh. If it's failed, click into the row to see the error.
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 Informational skill is enabled. If you disabled it in Chapter 6, the agent can't use the knowledge base for general questions.

URL mapping returns 0 discovered URLs

Symptom: You enter a website URL on the Map & Scrape page, click Map URL, and the discovered count stays at 0.

Most common cause: the site has very few crawlable pages. Single-page sites return an empty discovered set because the URL mapper reports only child URLs reachable from the seed. 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.

"Remember me" prompt didn't appear after a conversation

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 declined "Remember me" 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.

Memory persisted but routing rule didn't fire on a returning visitor

Symptom: A prospect comes back with memories already set, but a routing rule that should fire based on those memories doesn't.

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

Workaround: design routing rules 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 memory type added but skill doesn't see it

Symptom: You created a custom memory type, but the Qualify Prospect skill's memory dropdown doesn't show it.

The dropdown only lists enabled memory types. New custom memories default to enabled, but if you've toggled it off (the switch on the custom memory's card), it won't appear in skills until you toggle it back on.

Symptom: The embedded Cal.com widget appears, the visitor picks a time, but submission errors.

The Cal.com event URL configured on the Book Meeting skill must:

Be a public Cal.com event URL (e.g. https://cal.com/<handle>/<event-slug>)
Belong to a Cal.com account that's set up to accept external bookings
Match an event type that's published and active

If you used a placeholder or fictitious URL during configuration, swap it for a real Cal.com link before going live.

Email captured but classified into the wrong memory type

Symptom: The Memory 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 memory-type descriptions to know what counts. Two fixes:

Sharpen the memory type's description. A more specific description ("The prospect's individual job title — e.g. Head of Sales, CTO. Not the company's industry.") gives the extractor a clearer signal.
Edit the captured value directly on the prospect record. One-off cleanups can happen on the Prospects screen.

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

Pipeline ingestion fails on certain documents

Symptom: A document upload stalls at processing and eventually moves to failed.

Check the file size. 5 MB per file is the upper limit.
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 has consented. "Remember me" must be accepted for the prospect record to materialise.
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.

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