Skip to main content

Troubleshoot Sol Helps

Start with the exact symptom and preserve the browser time, hostname, assistant ID, route, request/delivery ID, and redacted error. Never share embed tokens, webhook secrets, or conversation content unnecessarily.

Widget does not appear​

Check bootstrap.js, authentication, sol-chat.umd.js, CSP, target ID, and the browser hostname in that order. Verify on an allowed domain in a private window. Success means one target mounts and opens.

Widget authentication fails​

Confirm window.ChatbotConfig contains the matching assistantId and token, then check the authentication response. Copy fresh values from the assistant; do not log them. Escalate with status and request time, not credentials.

Domain is rejected​

Compare window.location.hostname with the saved allowed-domain hostnames. Exact hosts and subdomains match. Fix the hostname entry and retest; do not temporarily allow unrelated domains.

Widget appears more than once​

Search the rendered page and tag manager for duplicate bootstrap scripts and duplicate targets. Remove the duplicate installation. Reinitialising one target reuses its root; two scripts or targets can produce two visible instances.

Inline launcher does not open the widget​

Confirm the widget initialised first, the element has data-sol-open, and data-sol-target matches the mounted target. Validate every context attribute. Inline placement is already open and cannot be closed programmatically.

Context does not appear​

Inspect the result of setContext() or the bounded launcher warning. Remove unknown fields, high-cardinality values, and invalid tags. Submit a new eligible message after the context update; old messages are not rewritten.

Conversation is not captured​

Check plan, enableChatLogging, visitor opt-in, assistant/date filters, traffic, and widget logging requests. Free widgets do not send chat logs. Success means the controlled eligible interaction appears in Captured Questions.

This is expected after opt-out. Do not bypass consent. Verify the prompt and privacy configuration, then use an explicitly opted-in controlled test.

Assistant does not answer​

Confirm the assistant is active, under quota, authenticated, and able to answer in preview. Record the assistant-request status. If preview works but embed does not, return to deployment/authentication checks.

Expected knowledge is not used​

Confirm the source is under the selected assistant and is Current, then ask a question explicitly grounded in it. Resolve stale/failed/contradictory sources. Do not add duplicates to manipulate retrieval.

Feedback does not appear​

Confirm the response was rated and a structured reason selected. Undo removes both. Check that the conversation itself was eligible and captured.

Insights filters show unexpected results​

Clear one exact filter at a time, verify period and assistant, then compare the stored surface, host, path, campaign, and widget version on an original record. Filters are server-enforced; context and attribution values must match exactly.

User cannot access Captured Questions or Insights​

Check conversations.read or insights.read and assistant scope. A scoped user may need one specific assistant instead of “all”. Use Roles and Permissions.

Webhook handoff fails​

Confirm Growth/Business, insights.export, enabled HTTPS configuration, and a receiver 2xx response within 10 seconds. Check signature verification against the raw body. Collect delivery ID, status, and redacted preview.

Plan limit blocks an action​

Review current plan and usage in Account. Reduce usage only after identifying the affected assistants/documents, or upgrade through the billing workflow. Do not delete data as a first diagnostic step.

Escalation bundle​

Provide the symptom, timestamp/timezone, page hostname/path, assistant ID, browser/version, relevant plan and role, consent state, exact status/reason, and request or delivery ID. Redact tokens, secrets, personal data, and message content unless support explicitly requires a secure transfer.