Common Issues

Troubleshooting guide for common problems and their solutions.

---

Login and Authentication

"Invalid credentials" Error

Symptoms:

• Login fails with "Invalid email or password"
• Credentials you know are correct don't work

Possible Causes:

• Typo in email or password
• Caps Lock is on
• Password was changed and you're using old password
• Account doesn't exist (wrong email)

Solutions:

1. Double-check email address

   • Verify spelling
   • Check for extra spaces
   • Ensure correct domain (@gmail.com vs @gnosari.com)

2. Reset your password

   • Click "Forgot Password" on login page
   • Enter your email address
   • Check inbox for reset link
   • Create new password

3. Verify Caps Lock is off

   • Passwords are case-sensitive
   • Check keyboard indicator

4. Try registering

   • If you get "Email already exists", account exists - reset password
   • If registration succeeds, use new credentials

---

Token Expiration (403 Errors)

Symptoms:

• Suddenly logged out mid-session
• "Unauthorized" errors
• Redirected to login page unexpectedly

Cause: Your authentication token expired. Tokens expire after a period of inactivity for security.

Solutions:

1. Log in again

   • Your session data is preserved
   • Enter credentials to continue

2. Enable "Remember Me"

   • Check "Keep me signed in" on login
   • Extends session duration

3. Stay active

   • Tokens refresh with activity
   • If away for extended periods, expect to re-login

Prevention: Gnosari automatically refreshes tokens while you're active. If you step away, save your work - you may need to re-authenticate.

---

"Account suspended" Error

Symptoms:

• Can't log in
• Error message says account is suspended

Possible Causes:

• Payment failure on paid plan
• Terms of service violation
• Security concern flagged

Solutions:

1. Check billing status

   • Failed payment can suspend account
   • Update payment method via email instructions

2. Contact support

   • Email: support@gnosari.com
   • Include account email address
   • Explain the issue

3. Review recent activity

   • Check email for suspension notice
   • Notice explains reason and resolution steps

---

Performance Issues

Slow Page Loading

Symptoms:

• Pages take a long time to load
• Spinners appear for extended periods
• UI feels sluggish

Possible Causes:

• Poor internet connection
• Too many browser extensions
• Browser cache issues
• Server performance (rare)

Solutions:

1. Check internet connection

   • Test speed: speedtest.net
   • Minimum recommended: 5 Mbps
   • Try different network if available

2. Try incognito/private mode

   • Rules out extension conflicts
   • Bypasses cache issues
   • Chrome: Ctrl+Shift+N (Windows) / Cmd+Shift+N (Mac)
   • Firefox: Ctrl+Shift+P (Windows) / Cmd+Shift+P (Mac)

3. Clear browser cache

   Chrome:

   • Settings → Privacy and Security → Clear browsing data
   • Select "Cached images and files"
   • Click "Clear data"

   Firefox:

   • Settings → Privacy & Security → Cookies and Site Data
   • Click "Clear Data"
   • Select "Cached Web Content"

   Safari:

   • Safari → Settings → Advanced → Show Develop menu
   • Develop → Empty Caches

4. Disable browser extensions

   • Ad blockers can interfere
   • Temporarily disable all extensions
   • Re-enable one by one to identify culprit

5. Update your browser

   • Use latest version
   • Check Help → About [Browser Name]

---

WebSocket Connection Failures

Symptoms:

• Real-time updates stop working
• Chat messages don't appear instantly
• Session updates delayed
• Console shows WebSocket errors

Possible Causes:

• Network firewall blocking WebSockets
• Corporate proxy interference
• Browser extension blocking

Solutions:

1. Check browser console

   • Open DevTools (F12)
   • Look for WebSocket errors
   • Note error messages

2. Try different network

   • Corporate networks often block WebSockets
   • Try mobile hotspot or home network

3. Disable VPN temporarily

   • Some VPNs interfere with WebSockets
   • Test without VPN

4. Contact IT department

   • If on corporate network
   • Request WebSocket access for *.gnosari.com

---

Chat Issues

Messages Not Sending

Symptoms:

• Click Send but message doesn't appear
• Message stuck in "sending" state
• Error notification appears

Possible Causes:

• Network connection lost
• Server timeout
• Invalid message content
• Session expired

Solutions:

1. Check connection

   • Verify internet is working
   • Reload the page
   • Try sending again

2. Check message length

   • Very long messages may timeout
   • Break into smaller messages
   • Recommended max: ~2000 characters per message

3. Verify session is active

   • Session may have ended
   • Create new session
   • Try again

4. Check for errors in console

   • Open DevTools (F12)
   • Check Console tab
   • Note error messages for support

---

Chat Widget Not Loading

Symptoms:

• Embedded chat widget doesn't appear on your website
• Widget shows briefly then disappears
• Error message in console

Possible Causes:

• Incorrect embed code
• JavaScript errors on page
• CORS policy blocking
• Agent/team identifier invalid

Solutions:

1. Verify embed code

   • Check you copied complete script tag
   • Ensure data-agent-id or data-team-id is correct
   • No typos in script URL

2. Check browser console

   • Look for CORS errors
   • Look for 404 errors (invalid ID)
   • Look for JavaScript errors

3. Test on different page

   • Isolate from your site's JavaScript
   • Create blank HTML page with only widget code
   • If works, conflict with existing code

4. Verify agent/team is public

   • Private agents won't load in embedded widget
   • Check agent settings
   • Set visibility to Public

Example embed code:

<script
  src="https://chat.gnosari.com/widget.js"
  data-agent-id="your-agent-id"
  data-theme="light"
  data-position="bottom-right"
></script>

---

Chat Response Delayed

Symptoms:

• AI takes a long time to respond
• Typing indicator shows for minutes
• Eventually times out

Possible Causes:

• Complex query requiring deep reasoning
• Agent configured with slow model
• High server load (rare)
• Network latency

Solutions:

1. Wait patiently

   • Complex queries take longer
   • Reasoning-enabled agents are slower but more accurate

2. Simplify your question

   • Break complex questions into steps
   • Ask one thing at a time

3. Check agent configuration

   • Some models are slower than others
   • Reasoning mode adds latency
   • Try disabling reasoning if enabled

4. Try during off-peak hours

   • If consistent slowness
   • May indicate high usage

---

Knowledge and Document Issues

Documents Not Processing

Symptoms:

• Uploaded document stuck in "Processing" state
• Upload fails with error
• Document never becomes available

Possible Causes:

• File format not supported
• File too large
• OCR failed on image/PDF
• Network timeout during upload

Solutions:

1. Check file format

   • Supported: PDF, TXT, MD, DOCX, CSV
   • Convert unsupported formats

2. Check file size

   • Maximum: 50MB per file (Free), 500MB (Pro/Enterprise)
   • Compress large files
   • Split into smaller documents

3. Verify file isn't corrupted

   • Try opening in another program
   • Re-export or re-save

4. Try uploading again

   • Delete failed upload
   • Upload fresh copy

---

Search Returns No Results

Symptoms:

• Searching knowledge returns nothing
• Know documents contain the information
• Similar queries work in other tools

Possible Causes:

• Documents still processing
• Search query too specific
• Indexing delay
• Special characters in query

Solutions:

1. Check document status

   • Ensure all documents show "Processed"
   • Wait for indexing to complete

2. Simplify search query

   • Use broader terms
   • Try synonyms
   • Remove special characters
   • Use fewer keywords

3. Try semantic search

   • Ask as a natural question
   • Example: "What is our refund policy?"
   • Instead of: "refund policy documentation"

4. Wait and retry

   • New documents need time to index
   • Wait 5-10 minutes after upload

---

Subscription and Billing

Payment Method Declined

Symptoms:

• Can't upgrade or change plan
• Payment method won't save
• Card declined error

Possible Causes:

• Insufficient funds
• Card expired
• Bank fraud protection
• Billing address mismatch

Solutions:

1. Verify card details

   • Check expiration date
   • Verify CVV code
   • Ensure billing address matches bank records

2. Contact your bank

   • May need to authorize charge
   • Confirm international transactions allowed (if applicable)
   • Check fraud protection settings

3. Try different payment method

   • Use different card
   • Try different card brand

4. Check billing address

   • Must match bank records exactly
   • Include correct ZIP/postal code

---

Can't Access Paid Features

Symptoms:

• Upgraded but still see limits
• Premium features not available
• Says "Upgrade to access"

Possible Causes:

• Upgrade not processed yet
• Payment pending
• Cache showing old plan
• Browser needs refresh

Solutions:

1. Refresh the page

   • Hard refresh: Ctrl+F5 (Windows) / Cmd+Shift+R (Mac)

2. Check subscription status

   • Go to Settings → Subscription
   • Verify current plan shows correctly
   • Check for "Pending" status

3. Wait 5 minutes

   • Upgrades can take a few minutes to propagate
   • Log out and log back in

4. Contact support if persists

   • Include account email
   • Screenshot of subscription page

---

API Integration Issues

API Requests Failing

Symptoms:

• API calls return 401 Unauthorized
• 403 Forbidden errors
• Connection refused

Possible Causes:

• Invalid API key
• API key revoked or inactive
• Wrong endpoint URL
• Missing authentication header

Solutions:

1. Verify API key

   • Check key in Settings → API Keys
   • Ensure status is "Active"
   • Generate new key if deleted

2. Check authentication header

   • Must use X-API-Key header
   • Verify no typos in header name
   • Example: headers: { 'X-API-Key': 'your-key' }

3. Verify endpoint URL

   • Use https://api.gnosari.com/api/v1/...
   • Check for typos
   • Ensure HTTPS (not HTTP)

4. Test with curl

   curl -H "X-API-Key: YOUR_KEY" \
     https://api.gnosari.com/api/v1/agents

---

Rate Limit Exceeded

Symptoms:

• API returns 429 status code
• "Rate limit exceeded" error
• Requests failing after some succeed

Cause: You've exceeded your subscription plan's API call limit.

Solutions:

1. Check current usage

   • Settings → Subscription
   • View "API Calls" usage meter

2. Wait for reset

   • Limits reset at start of billing cycle
   • Check when your billing cycle renews

3. Upgrade plan

   • Increase API call limits
   • Professional: 50,000/month
   • Enterprise: Unlimited

4. Optimize API usage

   • Cache responses when possible
   • Batch multiple requests
   • Reduce polling frequency

---

Getting Additional Help

Documentation

• Knowledge Base - Comprehensive guides
• API Documentation - API reference
• Video Tutorials - Step-by-step videos

Support Channels

Email Support:

• support@gnosari.com
• Response time: 24-48 hours (Free), 4-8 hours (Pro), 1-2 hours (Enterprise)

Community Forum:

• community.gnosari.com
• Ask questions
• Share solutions
• Connect with other users

Live Chat (Pro/Enterprise):

• Available during business hours
• In-app chat widget
• Instant assistance

When Contacting Support

Include:

• Account email address
• Detailed description of issue
• Steps to reproduce
• Screenshots (if visual issue)
• Browser and OS version
• Error messages from console (if applicable)

Example:

Email: john@example.com
Issue: Chat widget not loading
Browser: Chrome 120 on macOS 14
Steps:
1. Added embed code to website
2. Widget briefly appears
3. Disappears with console error: "CORS policy blocked"
Screenshot attached

---

Preventing Common Issues

Best Practices

1. Keep browser updated

   • Use latest stable version
   • Enable auto-updates

2. Stable internet connection

   • Minimum 5 Mbps recommended
   • Wired connection preferred for critical work

3. Save work frequently

   • Auto-save is enabled but save manually too
   • Draft important content offline first

4. Monitor usage limits

   • Check subscription usage regularly
   • Upgrade before hitting limits

5. Regular API key rotation

   • Rotate keys every 90 days
   • Prevents security issues

6. Test integrations in staging

   • Don't test API calls in production
   • Use separate keys for dev/staging/prod

---

Last updated: 2026-02-15