Troubleshooting Common Chat Issues

This tutorial helps you diagnose and resolve the most common issues encountered in the Keeptrusts chat workbench. Each section covers a specific problem category with symptoms, causes, and step-by-step fixes.

Use this page when

• You are experiencing connection problems, slow responses, or policy blocks in the chat workbench.
• You see authentication errors, model unavailability, or token limit issues.
• You need step-by-step diagnosis using browser developer tools and gateway status checks.

Primary audience

• Primary: Technical Engineers (self-service diagnosis)
• Secondary: Organization administrators (support escalation), Technical Leaders

Prerequisites

• Access to the Keeptrusts chat workbench (even if experiencing issues)
• Basic familiarity with the first conversation tutorial
• Browser developer tools knowledge is helpful but not required

Quick Reference: Known Issues Table

Issue	Symptom	Likely Cause	Quick Fix
Blank chat screen	White page after login	Auth handoff failed	Clear cookies and re-authenticate from the console
"Connection lost" banner	Red banner at top of chat	WebSocket or SSE disconnected	Check network; refresh the page
Spinning indicator forever	Loading spinner does not resolve	Gateway timeout	Verify gateway is running; check model provider status
"Policy blocked" message	409 response on send	Input policy triggered	Review the policy badge for details; rephrase your message
"Model unavailable"	Error when selecting a model	Model disabled or provider down	Try a different model; check provider status page
"Insufficient balance"	Send button disabled	Wallet empty	Top up your wallet or contact your admin
Response cut off mid-sentence	Incomplete model response	Token limit reached	Ask the model to continue or reduce your prompt length
"Session expired"	Redirected to login	JWT or gateway key expired	Re-authenticate from the console

Issue 1: Connection Problems

Symptoms

• Red "Connection lost" banner at the top of the chat interface
• Messages fail to send with a network error
• Streaming responses stop mid-generation

Diagnosis Steps

1. Check your internet connection — open another website to confirm connectivity.
2. Check the gateway status — the chat workbench connects through a Keeptrusts gateway. If the gateway is down, no messages can be processed.
3. Open browser developer tools (F12 or Cmd+Option+I) and check the Network tab for failed requests.
4. Look for CORS errors in the browser console — these indicate a misconfigured gateway or proxy.

Fixes

Cause	Fix
Internet disconnection	Reconnect and refresh the page — the workbench auto-reconnects on network restore
Gateway not running	Contact your admin to verify the gateway process (kt gateway run) is active
CORS misconfiguration	Admin must update KEEPTRUSTS_CORS_ALLOWED_ORIGINS to include the chat domain
Proxy or firewall blocking	Ensure your network allows connections to the gateway port (default: 41002)

Issue 2: Slow Responses

Symptoms

• Long delay between sending a message and seeing the first token
• Streaming starts but tokens appear very slowly
• Overall response takes more than 30 seconds

Diagnosis Steps

1. Check the model — larger models (e.g., GPT-4) are inherently slower than smaller ones.
2. Check prompt length — very long conversation histories increase processing time.
3. Check the time of day — model provider APIs experience peak-hour congestion.
4. Check the response time indicator — after the response completes, hover over the timestamp to see latency metrics.

Fixes

Cause	Fix
Large model with long context	Switch to a faster model for simple tasks; start a new conversation to reset context
Provider API congestion	Retry after a few minutes or switch to an alternative model provider
Gateway under load	Contact your admin to check gateway resource utilization
Slow network	Test your connection speed; use a wired connection if available

If you regularly experience slow responses with long conversations, use the context management tutorial techniques to keep your context window lean.

Issue 3: Policy Blocks

Symptoms

• "Your message was blocked by policy" error after sending
• 409 status code in network requests
• A policy badge appears with the block reason

Diagnosis Steps

1. Read the policy badge — click the badge to see which policy triggered and why.
2. Review your message — check if it contains terms or patterns that match a governance policy.
3. Check if the block is on input or output — input blocks prevent the message from reaching the model; output blocks redact or reject the model's response.

Fixes

Cause	Fix
Input contains restricted terms	Rephrase your message to avoid the flagged terms
Input contains PII	Remove personal data from your prompt
Prompt injection detected	Restructure your prompt — avoid instruction-like patterns in quoted text
Output policy triggered	The model's response was flagged; try rephrasing your request to guide the model differently

Policy blocks are governed by your organization's configuration. If you believe a block is incorrect, contact your admin to review the policy rules. Policy evaluations are logged in the event audit trail.

Issue 4: Authentication Errors

Symptoms

• Redirected to the login page unexpectedly
• "Session expired" message
• "Unauthorized" error (401) in the browser console
• Chat workbench loads but shows "Not authenticated"

Diagnosis Steps

1. Check if your console session is active — navigate to the Keeptrusts console. If you are logged out there, the chat session has also expired.
2. Check the browser clock — JWT validation fails if your system clock is significantly wrong.
3. Check for cookie issues — third-party cookie blocking can interfere with the PKCE auth handoff.

Fixes

Cause	Fix
JWT expired	Return to the console and re-open the chat workbench to trigger a fresh PKCE handoff
Cookies blocked	Allow cookies for the console and chat domains in your browser settings
System clock skew	Sync your system clock (Settings > Date & Time > Set Automatically)
Multiple tabs with different sessions	Close all chat tabs, log in to the console, and open a single chat tab

Issue 5: Model Unavailable

Symptoms

• "Model unavailable" error when selecting a model
• Model dropdown shows no options
• Previously available model is missing from the list

Diagnosis Steps

1. Check the model selector — expand the dropdown to see all available models.
2. Check model status — some models display a status indicator (green = available, red = down).
3. Check your team's model access — your admin may have restricted certain models to specific teams.

Fixes

Cause	Fix
Model provider is down	Check the provider's status page (e.g., status.openai.com); try a different model
Model disabled by admin	Contact your admin to re-enable the model for chat
Team restriction	Ask your admin to add your team to the model's access list
Gateway configuration changed	The gateway may need a config reload — contact your admin

Issue 6: Token Limit Exceeded

Symptoms

• Response is cut off mid-sentence
• "Maximum token limit reached" message
• Model returns an empty or very short response despite a complex prompt

Diagnosis Steps

1. Check the token count — the chat toolbar shows the approximate token count for the current context.
2. Check the model's context window — different models support different maximum token counts.
3. Check if the response hit the max output tokens — some policies set a maximum response length.

Fixes

Cause	Fix
Conversation history too long	Start a new conversation or summarize the history
Single prompt too large	Shorten your prompt; split complex requests into multiple messages
Model's context window exceeded	Switch to a model with a larger context window
Admin-set max response length	Contact your admin to adjust the policy if the limit is too restrictive

To continue a cut-off response, send a follow-up message:

Please continue from where you left off.

Issue 7: Chat Workbench Not Loading

Symptoms

• Blank white page after clicking Chat in the console
• Infinite loading spinner
• JavaScript errors in the browser console

Diagnosis Steps

1. Hard-refresh the page — press Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows/Linux).
2. Clear browser cache for the chat domain only (not all sites).
3. Try an incognito/private window to rule out extension interference.
4. Check browser compatibility — the chat workbench requires a modern browser (Chrome, Firefox, Edge, Safari).

Fixes

Cause	Fix
Stale cached assets	Hard-refresh or clear cache for the chat domain
Browser extension conflict	Disable extensions temporarily (especially ad blockers and privacy tools)
Outdated browser	Update to the latest version of your browser
Console-to-chat handoff failure	Log out of the console, log back in, and re-open chat

Issue 8: Unexpected Response Content

Symptoms

• Model response seems irrelevant to your question
• Response contains information you did not ask for
• Response quality is significantly lower than expected

Diagnosis Steps

1. Check the selected model — you may have accidentally switched to a less capable model.
2. Review your system prompt — custom system prompts can influence response behavior.
3. Check the conversation context — the model may be referencing earlier messages that shifted the context.
4. Check for knowledge base bindings — bound knowledge assets can influence the response.

Fixes

Cause	Fix
Wrong model selected	Switch to the intended model in the toolbar
System prompt mismatch	Review and update your system prompt settings
Context drift	Start a new conversation with a fresh context
Knowledge base interference	Unbind irrelevant knowledge assets from the conversation

Getting Further Help

If none of the above steps resolve your issue:

1. Check the Keeptrusts status page for any ongoing incidents.
2. Collect diagnostic information: browser name/version, error messages, network request details from developer tools.
3. Contact your Keeptrusts administrator with the diagnostic information.
4. Check the event log in the Keeptrusts console for detailed policy evaluation results.

Summary

You now know how to diagnose and resolve the most common chat workbench issues:

• Connection problems and network troubleshooting
• Slow response diagnosis and optimization
• Policy block interpretation and resolution
• Authentication error recovery
• Model availability troubleshooting
• Token limit management
• Page loading failures
• Unexpected response content

For AI systems

• Canonical terms: Keeptrusts chat workbench, connection lost, gateway timeout, policy blocked (409), auth handoff failed, model unavailable, insufficient balance, session expired, CORS, WebSocket, SSE.
• Key environment variables: KEEPTRUSTS_CORS_ALLOWED_ORIGINS, gateway port (41002), kt gateway run.
• Common fixes: clear cookies + re-auth, verify gateway running, check provider status, adjust max_tokens, top up wallet.
• Best next pages: First Conversation, Policy Feedback, Streaming Responses.

For engineers

• Prerequisites: browser developer tools (F12 / Cmd+Option+I); knowledge of your gateway URL and port.
• Diagnosis workflow: Network tab for failed requests → Console tab for CORS errors → check gateway process (kt gateway run) → check provider status page.
• Key quick fix: "Blank chat screen" = clear cookies + re-authenticate from console (handoff token is single-use).

For leaders

• Most chat issues resolve with self-service diagnosis — this page reduces support ticket volume.
• Persistent connection failures indicate infrastructure gaps (gateway uptime, CORS config) requiring ops attention.
• Policy blocks are governance working as intended; escalation paths exist for legitimate edge cases.
• Track recurring issues in the Events dashboard to identify systemic patterns.

Next steps

• Tutorial: Your First Conversation — verify the basics are working after troubleshooting.
• Tutorial: Understanding Policy Feedback — interpret policy blocks and adjust prompts.
• Tutorial: Streaming Responses — understand streaming behavior and timeout expectations.