Developer / Troubleshooting recipes

Troubleshooting & diagnostics

Quick solutions to verified operational issues, error codes, and configuration conflicts across the crawler, widget, ingestion pipeline, and API.

Diagnostic recipes

Structured by symptom, root cause, verification check, and verified resolution.

403 WIDGET_ORIGIN_NOT_ALLOWED

Symptom

The widget bubble fails to appear on your website, or browser DevTools console prints a 403 Forbidden error.

Root Cause

The embedding website domain is not registered in the assistant’s Allowed Domains list.

Verification

Open browser DevTools -> Network tab. Filter for "config". Check the request origin header and the 403 response payload.

Fix

Navigate to Dashboard -> Assistant Settings -> Allowed Domains. Add your domain (e.g., "example.com" or "*.example.com"). Save changes. Note: Public widget configuration is cached server-side in Redis for up to 300 seconds (5 minutes) with best-effort invalidation upon dashboard updates.

Content Security Policy (CSP) Blocking Widget

Symptom

Browser console prints: "Refused to load the script... because it violates the following Content Security Policy directive".

Root Cause

Your website enforces a Content Security Policy that restricts external script execution or network requests.

Verification

Inspect response headers of your host HTML page for the "Content-Security-Policy" header.

Fix

Add the WebChat AI origin to your server’s CSP header: script-src 'self' https://api.webchat.ai; connect-src 'self' https://api.webchat.ai; font-src 'self' https://fonts.gstatic.com;

Crawler Discovers 0 Pages or Stops Early

Symptom

Crawl job status switches to completed or failed with 0 or 1 pages indexed.

Root Cause

The target site robots.txt forbids crawler user-agents, the site is a Single Page App (SPA) without server-rendered HTML links, or the URL resolved to a private/internal IP blocked by SSRF defense.

Verification

Visit https://yourdomain.com/robots.txt in your browser. Inspect whether "Disallow: /" is set. Check if page links require JavaScript execution.

Fix

Adjust robots.txt to allow crawling, provide an XML sitemap URL, or switch the assistant to "Files" / "Mixed" mode and upload exported HTML/PDF documentation directly.

File Upload Rejected or Document Shows "Failed"

Symptom

Document upload modal displays a red error banner, or document status shows "failed" in the Knowledge Base table.

Root Cause

File exceeds 10 MB, batch has more than 5 files, PDF is encrypted/password-protected, PDF exceeds 100 pages, or file type is unsupported.

Verification

Verify file size and page count on your local machine. Try opening the PDF without entering a password.

Fix

Remove password encryption before uploading, split documents into batches under 10 MB, and click the "Retry" button next to any failed document in the Knowledge Base table.

Assistant Answers: "I do not have enough information"

Symptom

The assistant consistently returns the fallback unknown answer response even for questions related to your product.

Root Cause

The RAG hybrid retrieval score fell below the grounding confidence threshold to prevent hallucination.

Verification

Inspect Knowledge Base -> Documents. Verify documents are in "completed" status. Review whether the exact terminology or entity names exist in the ingested text.

Fix

Add an FAQ document (.md or .pdf) containing explicit definitions and concise answers to frequently asked visitor questions, then re-test in the Widget Test harness.

429 MESSAGE_LIMIT_REACHED

Symptom

Widget displays: "Message limit reached for this month. Please contact the site administrator."

Root Cause

Your tenant has reached the monthly message quota allocated to your active subscription plan.

Verification

Check Dashboard -> Analytics or Dashboard -> Billing to review monthly message usage bars.

Fix

Upgrade your subscription tier in the Billing panel. Upgrades take effect immediately and restore widget query capacity.

Testing in the staging harness

Verify fixes before redeploying to production environments.

Whenever you adjust assistant settings, test the change inside the dedicated dashboard test harness at /widget-test. This isolated dashboard test page runs with dashboard origin permissions and hot reloads configuration changes.

Need further assistance?

If you continue encountering unexplained issues, check your server container logs for uncaught exceptions or open a support inquiry through your account dashboard.

Troubleshooting & diagnostics

Quick solutions to verified operational issues, error codes, and configuration conflicts across the crawler, widget, ingestion pipeline, and API.

Diagnostic recipes

Structured by symptom, root cause, verification check, and verified resolution.

403 WIDGET_ORIGIN_NOT_ALLOWED

Symptom

The widget bubble fails to appear on your website, or browser DevTools console prints a 403 Forbidden error.

Root Cause

The embedding website domain is not registered in the assistant’s Allowed Domains list.

Verification

Open browser DevTools -> Network tab. Filter for "config". Check the request origin header and the 403 response payload.

Fix

Content Security Policy (CSP) Blocking Widget

Symptom

Browser console prints: "Refused to load the script... because it violates the following Content Security Policy directive".

Root Cause

Your website enforces a Content Security Policy that restricts external script execution or network requests.

Verification

Inspect response headers of your host HTML page for the "Content-Security-Policy" header.

Fix

Add the WebChat AI origin to your server’s CSP header: script-src 'self' https://api.webchat.ai; connect-src 'self' https://api.webchat.ai; font-src 'self' https://fonts.gstatic.com;

Crawler Discovers 0 Pages or Stops Early

Symptom

Crawl job status switches to completed or failed with 0 or 1 pages indexed.

Root Cause

The target site robots.txt forbids crawler user-agents, the site is a Single Page App (SPA) without server-rendered HTML links, or the URL resolved to a private/internal IP blocked by SSRF defense.

Verification

Visit https://yourdomain.com/robots.txt in your browser. Inspect whether "Disallow: /" is set. Check if page links require JavaScript execution.

Fix

Adjust robots.txt to allow crawling, provide an XML sitemap URL, or switch the assistant to "Files" / "Mixed" mode and upload exported HTML/PDF documentation directly.

File Upload Rejected or Document Shows "Failed"

Symptom

Document upload modal displays a red error banner, or document status shows "failed" in the Knowledge Base table.

Root Cause

File exceeds 10 MB, batch has more than 5 files, PDF is encrypted/password-protected, PDF exceeds 100 pages, or file type is unsupported.

Verification

Verify file size and page count on your local machine. Try opening the PDF without entering a password.

Fix

Remove password encryption before uploading, split documents into batches under 10 MB, and click the "Retry" button next to any failed document in the Knowledge Base table.

Assistant Answers: "I do not have enough information"

Symptom

The assistant consistently returns the fallback unknown answer response even for questions related to your product.

Root Cause

The RAG hybrid retrieval score fell below the grounding confidence threshold to prevent hallucination.

Verification

Inspect Knowledge Base -> Documents. Verify documents are in "completed" status. Review whether the exact terminology or entity names exist in the ingested text.

Fix

Add an FAQ document (.md or .pdf) containing explicit definitions and concise answers to frequently asked visitor questions, then re-test in the Widget Test harness.

429 MESSAGE_LIMIT_REACHED

Symptom

Widget displays: "Message limit reached for this month. Please contact the site administrator."

Root Cause

Your tenant has reached the monthly message quota allocated to your active subscription plan.

Verification

Check Dashboard -> Analytics or Dashboard -> Billing to review monthly message usage bars.

Fix

Upgrade your subscription tier in the Billing panel. Upgrades take effect immediately and restore widget query capacity.

Testing in the staging harness

Verify fixes before redeploying to production environments.

Need further assistance?

If you continue encountering unexplained issues, check your server container logs for uncaught exceptions or open a support inquiry through your account dashboard.