Troubleshooting

Symptoms in roughly the order they happen, each with the one thing to check first. Most of these are a two-minute fix.

The launcher bubble doesn't appear

Open your browser's developer console on the page and look at the network request to /widget/session.

403 — Origin not allowed: The page's origin isn't on the site key's allowlist. Check for the exact scheme and subdomain: https://www.example.com and https://example.com are different origins and the www one is the classic miss. See Allowed origins.
403 — Unknown site key: The data-site-key doesn't match any workspace. Copy it fresh from Site keys — a truncated paste is the usual cause.
402: The workspace has no active subscription. The widget stays offline by design; see Billing.
No request at all: The script never ran. Confirm the tag is actually in the served HTML (view source, not your template), that it's before </body>, and that data-site-key is present — a missing key logs [doorwick] missing data-site-key to the console.

Also worth ruling out: an ad blocker, or a Content Security Policy on your site that blocks the script or the iframe.

Messages send but nothing reaches my inbox

Check you're looking at the right workspace — the dashboard defaults to all of them, but a sidebar filter persists. Then check the status tabs: if the AI escalated, the thread is under Pending human, not Open.

The AI never replies

Walk these in order — it's nearly always one of the first two:

Is the agent enabled? The checkbox on the AI agent page is the master switch, separate from having saved a key.
Is the thread on AI handling? The pill in the thread header. Conversations that started before you enabled the agent stay human-handled, and a handoff sets it to human permanently until you flip it back.
Is the key valid? A provider error posts a system note in the thread — "Sorry, I couldn't generate a reply" — and escalates. If you see that, the call is failing.
Is the model id right? It's free text and passed straight through, so a typo or a retired model reaches the provider and comes back as an error.

A knowledge source says failed

No AI profile configured for this workspace: Indexing runs on your provider key. Set up the AI agent first.
Anthropic has no embeddings API: Exactly what it says: Anthropic serves no embeddings endpoint, so there's nothing to index against. Fill in AI agent → Embeddings with a base URL or key that points at something serving /v1/embeddings — OpenAI or a local Ollama both work, and chat stays on Claude.
An authentication or 401 error: The embeddings call was rejected by whatever it reached. Check the key in AI agent → Embeddings belongs to the endpoint in the base URL beside it — a key for one provider sent to another is the usual cause.
Fetch failed (404 / 403 / 500): The URL didn't return a page. Check it's publicly reachable — anything behind a login or a bot wall won't fetch. Paste the text instead.
No indexable content: The fetch succeeded but stripped to nothing usable, which happens with pages rendered entirely in JavaScript. Paste the text instead.

Fix the cause, then hit Reindex — the source retries from scratch.

The AI answers, but says it doesn't know

That's the design working, not a bug: with knowledge indexed but nothing relevant to the question, the agent is told to say so and escalate rather than improvise. Open the escalated threads, read what people actually asked, and write a source that answers it. See Knowledge and citations.

If it says it doesn't know about something you have written up, check the source is ready rather than pending or failed, and that the wording in the source resembles the words visitors use.

Answers have no citations

Citations only appear when relevant passages were actually retrieved. No sources indexed means no citations — the agent falls back to answering from the model's own knowledge, which is exactly the behaviour to avoid in production. Add at least one source.

The Help tab isn't showing

The tab is hidden on purpose when no Knowledge source is ready, even if Help search is on. Add a source, wait until it says ready, then reload the widget. If sources are ready and you still see no tab, confirm Help search is on under Widget → Behavior and that you saved.

A logged-in visitor still shows as anonymous

The signature didn't verify. In order of likelihood: the HMAC was computed over a different string than the one sent as external_id (a number versus a string is the usual culprit), the wrong secret was used, or window.doorwickSettings is being set after the widget script rather than before it. See Verified visitors.

A settings page isn't there

AI settings, Widget, Site keys, Team, Getting started and Billing are owner-only. If you're an agent they aren't in your sidebar, and going straight to the URL returns a 404 rather than a warning. Ask an owner to promote you, or to make the change for you.

An invitation isn't working

The link says it's no longer valid: It was revoked, or already used. Ask for a new one — revoking really does kill the link.
The link says it has expired: Invitations last seven days. Send a fresh one from Team.
It says you're signed in as the wrong person: The invitation names one address and you're signed in as another. Sign out from the button on that page, then open the link again.
Nothing arrived: Check the spelling on the pending invitation, and the recipient's spam folder. Revoke and re-send if the address was wrong.

A setting won't save

If saving bounces you to billing with a note about preview, the workspace isn't subscribed — settings pages are readable but not writable until it is. Your inbox and your export keep working either way.

Still stuck

Tell us what you saw, what you expected, and the network response the widget got. That last one turns most of these into a one-line answer.