Troubleshooting

Common issues and their solutions.

Data Sources

Data source isn't processing

Symptoms:

• Status stuck at "Processing"

• Process logs show errors

• No new documents indexed

Solutions:

1. Check Process Logs

   • Navigate to Data → [Your Data Source] → Logs

   • Look for specific error messages

   • Common issues: authentication, connectivity, format

2. Verify Authentication

   • Re-authenticate if using OAuth (Google Drive, OneDrive)

   • Check API tokens haven't expired

   • Verify credentials are correct

3. Test Connectivity

   • For websites: Ensure URL is publicly accessible

   • Check for robots.txt restrictions

   • Verify SSL certificates are valid

4. Check File Formats

   • Ensure files are in supported formats

   • Try re-uploading files

   • Check file isn't corrupted

5. Manual Retry

   • Click "Retry Processing"

   • If issue persists, delete and recreate

Confluence pages not syncing

Common Issues:

Authentication Expired:

• Re-authenticate: Data → Confluence → Settings → Reconnect

Insufficient Permissions:

• Ensure Confluence account has read access to spaces

• Check space permissions in Confluence admin

Space Selection:

• Verify correct spaces are selected in settings

• Some pages may be restricted

Solution:

1. Go to Data → Confluence source
2. Click "Test Connection"
3. Review error message
4. Update credentials or permissions
5. Trigger manual sync

Google Drive files not appearing

Possible Causes:

1. Shared Drive Access:

   • Enable "Shared Drives" during OAuth

   • Grant access to specific drives

2. File Type Filtering:

   • Check file type settings

   • Ensure PDFs/Docs aren't excluded

3. Folder Selection:

   • Verify correct folders are selected

   • Check folder permissions

Solution:

1. Navigate to Data → Google Drive
2. Click "Configure"
3. Select "Reconnect"
4. Grant all requested permissions
5. Select specific folders or "All Files"
6. Save and trigger sync

AI Responses

Agent can't answer questions

Symptoms:

• "I don't have information about that"

• No citations in response

• Generic or off-topic answers

Diagnosis:

1. Check Data Coverage

   • Search knowledge base for relevant content

   • Verify data sources contain the information

   • Check if documents processed successfully

2. Verify Data Source Connection

   • Go to Agent settings

   • Confirm data sources are selected

   • Ensure sources are active (not disabled)

3. Test Query Variations

   Instead of: "What about pricing?"
   Try: "What are the pricing plans?"

4. Review Citations

   • Check what sources the AI attempted to use

   • Verify relevance of cited documents

Solutions:

• Add Missing Information: Create KB article or add data source

• Improve Data Quality: Better document structure, clear headings

• Try Different Strategy: Switch from Redwood to Cedar for ambiguous queries

• Adjust Instructions: Provide more context in system prompt

Responses are inaccurate

Common Causes:

1. Outdated Information

   • Data source hasn't synced recently

   • Old documents still in index

2. Conflicting Information

   • Multiple sources with different information

   • Priority not set correctly

3. Hallucination

   • AI generating unsupported information

   • Enable "Private Data Only" mode

Solutions:

1. Refresh Data Sources

   Data → [Source] → Sync Now

2. Enable Private Data Only

   Agent Settings → Privacy → Private Data Only ✓

3. Review and Edit in Inbox

   Inbox → Find interaction → Mark as Inaccurate
   → Provide correct answer → Agent learns

4. Add Source Prioritization

   Use Cypress strategy for tier-based retrieval
   Tier 1 = Most authoritative sources

Responses are too slow

Symptoms:

• Response time > 5 seconds

• Timeout errors

• Poor user experience

Diagnosis:

Check response time breakdown:

• Vector search: Should be < 200ms

• LLM completion: Should be < 2s

• Total: Should be < 3s

Solutions:

1. Switch to Faster Strategy

   Agent Settings → RAG Strategy → Redwood
   (Reduces 2-3 seconds compared to Cypress)

2. Reduce topK

   Agent Settings → Advanced → topK = 5
   (Fewer documents = faster processing)

3. Enable Caching

   Agent Settings → Performance → Cache Enabled ✓

4. Use Streaming

   // API request
   { stream: true }
   // User sees response as it's generated

5. Check System Status

   • Visit status.twig.so

   • Check for ongoing incidents

API Issues

Authentication failures

Error: 401 Unauthorized

Causes:

• Invalid API key

• Expired key

• Incorrect header format

Solutions:

1. Verify API Key

   # Correct format
   curl -H "Authorization: Bearer sk_live_abc123..."
   
   # ❌ Wrong
   curl -H "Authorization: sk_live_abc123..."

2. Check Key Status

   • Settings → API Keys

   • Ensure key is active (not revoked)

3. Generate New Key

   • Settings → API Keys → Generate New Key

   • Update your application

Rate limit exceeded

Error: 429 Too Many Requests

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

Solutions:

1. Implement Exponential Backoff

   async function retryWithBackoff(fn, maxRetries = 3) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await fn();
       } catch (error) {
         if (error.status === 429 && i < maxRetries - 1) {
           await sleep(Math.pow(2, i) * 1000);
           continue;
         }
         throw error;
       }
     }
   }

2. Upgrade Plan

   • Free: 20 req/min → Pro: 100 req/min

   • Contact sales for higher limits

3. Optimize Request Patterns

   • Batch similar requests

   • Cache frequent queries

   • Reduce polling frequency

Invalid request format

Error: 400 Bad Request

Common Issues:

1. Missing Required Fields

   // ❌ Missing agentId
   {
     "prompt": "What is pricing?"
   }
   
   // ✅ Correct
   {
     "prompt": "What is pricing?",
     "agentId": "agent-123"
   }

2. Incorrect Data Types

   // ❌ topK as string
   { "topK": "5" }
   
   // ✅ topK as number
   { "topK": 5 }

3. Invalid JSON

   • Validate JSON before sending

   • Check for trailing commas

   • Ensure proper escaping

Integration Issues

Browser extension not working

Symptoms:

• Extension icon is grayed out

• No response when clicking

• "Not logged in" error

Solutions:

1. Check Login Status

   • Click extension icon

   • Click "Login" if not authenticated

   • Allow pop-ups if blocked

2. Update Extension

   • Chrome Web Store → Twig AI → Update

   • Restart browser

3. Clear Extension Data

   • Right-click extension icon → Options

   • Click "Clear Data"

   • Log in again

4. Check Permissions

   • Extension may need additional permissions

   • Review and accept prompts

Slack integration not responding

Symptoms:

• Bot doesn't reply in channels

• Commands not recognized

• "Bot not installed" message

Solutions:

1. Verify Installation

   • Slack workspace → Apps

   • Check Twig AI is installed

   • Reinstall if missing

2. Check Channel Permissions

   • Invite bot to channel: /invite @TwigAI

   • Verify bot has read/write permissions

3. Test with Direct Message

   • DM @TwigAI to test bot

   • If working, issue is channel-specific

4. Reconnect Integration

   • Twig AI → Integrations → Slack

   • Click "Reconnect"

   • Authorize again

Zendesk app not loading

Symptoms:

• Sidebar empty

• "Failed to load" error

• App not appearing

Solutions:

1. Refresh Ticket

   • Reload the ticket page

   • Clear browser cache

2. Check App Installation

   • Zendesk Admin → Apps → Manage

   • Verify Twig AI is enabled

   • Check configuration settings

3. Verify API Connection

   • Twig AI → Settings → Integrations → Zendesk

   • Test connection

   • Update credentials if needed

4. Browser Console Errors

   • Open DevTools (F12)

   • Check Console tab for errors

   • Report to support if needed

Performance Issues

High memory usage

Symptoms:

• Browser tab using lots of RAM

• Slow UI responsiveness

• Tab crashes

Solutions:

1. Limit Open Conversations

   • Close old Playground sessions

   • Clear conversation history

2. Disable Streaming

   • Use non-streaming mode for lower memory

   • Streaming keeps connection open

3. Use Dedicated App

   • Desktop app (if available) uses less memory

   • Or use API instead of web UI

Slow dashboard loading

Symptoms:

• Analytics page takes > 10s to load

• Charts not rendering

• Timeouts

Solutions:

1. Reduce Date Range

   • Select shorter time period (e.g., 7 days vs 90 days)

   • Large datasets take longer to query

2. Clear Cache

   • Browser cache may be corrupted

   • Hard refresh: Ctrl+Shift+R (Cmd+Shift+R on Mac)

3. Check Data Volume

   • Large organizations may need longer load times

   • Contact support for optimization

Still Having Issues?

Collect Diagnostic Information

Before contacting support, gather:

1. Error Details

   • Full error message

   • Error code

   • Screenshot if visual issue

2. Request Details

   • Timestamp

   • Request ID (from API response headers)

   • User ID / Organization ID

3. Environment

   • Browser type and version

   • Operating system

   • Network connection type

4. Steps to Reproduce

   • What you were doing

   • What you expected to happen

   • What actually happened

Contact Support

• Email: [email protected]

• In-App Chat: Click chat icon (bottom right)

• Status Page: status.twig.so

• Community: community.twig.so

Emergency Support (Enterprise Only)

For production-critical issues:

• Phone: Provided in enterprise agreement

• Slack Connect: Direct channel to support team

• Response Time: 4 hours guaranteed