Troubleshooting

Most problems fall into a handful of categories. Start with the symptom below. For almost everything, the browser's developer tools help: press F12, then look at the Console tab (the widget writes a short warning there when it cannot start) and the Network tab (filter for widget or chat).

The widget does not appear#

Work through these in order.

1. Is the script on the page? View the page source (not the inspected DOM) and search for widget.js. If it is missing, the snippet was not saved or a cache is serving an older page. Purge caches (WordPress cache plugins, Cloudflare, host-level caches) and hard-refresh. Platform instructions: HTML, WordPress, Shopify, Wix, Squarespace, Tag Manager.
2. Does widget.js load? In the Network tab it should return status 200. If it is blocked, check your Content Security Policy (script-src), an ad blocker or privacy extension, or a corporate filter. Try a private window with extensions disabled.
3. Is the site id valid? The data-site value looks like site_ followed by 16 characters. A typo or a missing character makes the widget log "missing or invalid data-site" in the console and stop.
4. Does the configuration request succeed? Look for widget/config in the Network tab. If it is blocked by CORS or answers with origin_not_allowed, see the next section.
5. Is the response "available": false? Then there is nothing to show; see "No published agent" below.
6. Page rules or launcher settings. The site's page rules may exclude the current page, hide on mobile may be on while you test on a phone, or a launcher delay may be set. Check the widget settings. See Widget customization.
7. Is it covered? Another element with a very high z-index may sit on top of the launcher, or a cookie banner may cover the corner. Adjust the offsets or z-index in the window settings.
8. Settings are cached briefly. Changes can take up to about a minute to reach a visitor's browser. Hard-refresh.

Origin blocked ("origin_not_allowed", CORS errors)#

The console shows a message such as "this domain is not in the allowed origins" or a CORS error on widget/config.

• Open the site in the dashboard and add the exact origin of the page: scheme, host and port, no path and no trailing slash. https://www.example.com and https://example.com are different origins; add both if you use both. Staging, preview and localhost addresses are also separate origins. See allowed origins.
• Wildcards work for subdomains: https://*.example.com (not the bare domain).
• If the list is empty the API allows every origin; if you recently added a first entry, make sure it covers every domain where the widget is installed.
• Pages opened from a file (file://) or sandboxed iframes send the origin null, which is only allowed while the list is empty. Use a real local server such as http://localhost:3000 when testing.

No published agent#

The widget hides itself, and the config request returns available: false, when the site has no agent that is both enabled and published. Open Agents, make sure the agent belongs to the right site, is enabled, shows a published version number, and is the site's default (or the only enabled one). Publishing fails with a list of problems if the model chain is empty or invalid; fix those first. See Playground, publishing and rollback.

Plan limit reached or account suspended#

• Monthly conversation limit. On Free, new conversations cannot start once the 100 monthly conversations are used; on paid plans, after the allowance plus the 10% grace buffer. Either way they resume next month or after an upgrade. The dashboard overview and billing page show usage. See Billing and plans.
• Agent message cap. If you set a monthly message cap on an agent (Rules and limits tab), it stops answering when reached.
• Suspended account. A suspended account (for example after an unresolved billing or abuse issue) makes the widget unavailable. Check for emails from us and your billing status, or contact support.
• Over-limit after a downgrade. Features above your plan (webhooks, custom CSS, takeover) stop working, and publishing is blocked until the agent fits the plan.

The AI does not reply, or says it is having trouble#

Visitors see the agent's failure message ("Sorry, I'm having trouble responding right now...") when every step of the model chain fails. Open the conversation in the dashboard and look at its trace to see each attempt, the model, the HTTP status and the error.

You see	Likely cause	What to do
401 or "invalid API key"	Wrong, deleted or revoked key; trailing spaces.	Create a new key at the provider and rotate it in AI providers. Test it.
403, "permission" or "model access"	The key cannot use the chosen model, or the provider blocks your region.	Pick another model or enable access at the provider.
404, "model not found"	The model name is retired or unavailable to your account.	Choose a current model from the dashboard list.
429 (rate limit) or "quota"	Too many requests, or no credit left.	Add credit, raise your tier, or add a fallback step on another provider.
402 or "insufficient balance/credit"	Prepaid balance is empty.	Top up at the provider, then Test the key.
5xx, "overloaded"	Provider outage or busy period.	Add a fallback step on a different provider so the chat survives outages.
Tools not called, or "tools not supported"	The selected model cannot call tools.	Pick a model marked as supporting tools.

Per-provider guidance: Anthropic, OpenAI, Gemini, OpenRouter, DeepSeek. Keys marked failing in AI providers need attention first.

Slow replies and timeouts#

• Choose a faster model. Smaller models answer in a second or two; large reasoning models can take much longer.
• Reduce the work per turn. Long knowledge text, a large history window and high max-token settings all slow replies and raise cost.
• Check tools. A slow tool endpoint adds its full response time to the reply. Aim for under two seconds, and set a sensible tool timeout.
• Step timeouts. Each model step has a timeout (default 30 seconds, maximum 55). When it passes, the next step is tried. The whole reply also has an overall budget of roughly half a minute that the platform sets, so a long step timeout does not extend it. Very slow providers may need a longer timeout, but a fast first step with a fallback usually works better.
• Expect a polling rhythm. Replies appear when they are complete (there is no token-by-token streaming), and operator messages arrive within a couple of seconds because the widget checks for updates every few seconds.

Emails not arriving#

This covers lead notifications, handoff emails, team emails from the AI, visitor transcripts, invitations and password resets.

• Check the spam or junk folder, and allow mail from the sending address.
• Check the recipients: for handoffs and AI emails the order is the escalation recipients, then the lead notification addresses, then the account owners and admins. Lead notification emails go only to the notification addresses of the lead capture settings.
• Playground tests never send lead, handoff or team emails. Test on the live widget.
• A typo in an address is silently dropped when the settings are saved if it is not a valid email address. Re-open the settings and confirm the list.
• Corporate mail systems sometimes quarantine automated mail. Ask your IT team to allowlist the sender.
• If invitations or password reset emails never arrive for anyone, contact support, as the sending service may need attention.

Webhooks failing#

• Open Webhooks and the endpoint's delivery log. The last status code and error show what went wrong.
• No deliveries at all: your plan may not include webhooks (Free), the endpoint may be inactive, the event may not be in its subscription list, or the endpoint is scoped to a different site.
• Blocked address: the URL points to a private or local address. Endpoints must be reachable from the public internet over HTTPS.
• Redirects: a 301 or 302 response counts as a failure. Use the final URL.
• 4xx from your server: the receiver rejected the request and it will not be retried automatically (except for 408, 425, 429). Fix the cause, then redeliver it. The most common cause is a failing signature check: verify the raw body, the secret, and your server clock.
• Timeouts: respond within 10 seconds; do slow work in the background.

Cache and CDN issues#

• Old version of your page. Page caches and CDNs may serve HTML without the snippet. Purge them.
• Optimization plugins. Plugins that combine, minify or delay JavaScript can break or delay the widget. Exclude the widget script from them.
• Settings changes not showing. The widget configuration is cached for a short time (around 30 seconds) and revalidated with an ETag. If you changed the colors and still see the old ones, wait a minute and hard-refresh. Check that you edited the right site.
• A proxy in front of the API. If your organization routes traffic through a proxy that strips headers (such as X-ST-Token) or caches POST responses, chat calls can fail. Test from a different network.
• The conversation seems stuck on an old state. The widget remembers the conversation in the browser. Use End chat then Start new chat, or clear site data for your domain.

Still stuck?#

The FAQ answers common questions about limits and what SiteTrellis does not do. Otherwise contact support and include: your site id (site_...), the page URL, what you expected and what happened, and any request_id from an error response (visible in the Network tab). Please do not send your API keys.