Common Issues Overview
This troubleshooting guide addresses the most frequently encountered issues with Ravvio platform and provides step-by-step solutions to resolve them quickly.Issue Categories
Agent Performance
Issues related to agent responses, behavior, and functionality
Integration Problems
Website integration, embedding, and connectivity issues
System Performance
Platform performance, speed, and reliability concerns
Account & Billing
Account access, billing, and subscription-related problems
Agent Not Responding
Knowledge Base Issues
Documents Not Uploaded or Indexed
Documents Not Uploaded or Indexed
Problem Symptoms:
- Agent provides generic responses instead of specific information
- No reference to uploaded documents in responses
- “I don’t have information about that” responses to known topics
- Navigate to Knowledge Base section in dashboard
- Verify documents are listed and status shows “Ready”
- Check document processing status and error messages
- Confirm file formats are supported (PDF, DOCX, TXT, CSV, JSON, MD, HTML)
- Re-upload documents if processing failed
- Wait for index building to complete (can take several minutes)
- Check file size limits and format compatibility
- Verify document content is text-based, not image-only
- Contact support if processing continues to fail
Index Health Problems
Index Health Problems
Problem Indicators:
- Index status shows “Building” for extended periods
- Index status shows “Error” with failed processing
- Agent responses inconsistent with uploaded content
- Knowledge base search not finding relevant information
- Check index health status in dashboard
- Review error logs and processing messages
- Verify document integrity and content quality
- Attempt to reprocess problematic documents
- Remove and re-upload problematic documents
- Ensure documents contain readable text content
- Break large documents into smaller sections
- Contact support for persistent indexing issues
System Prompt Configuration
1
Incomplete Prompt Configuration
Issue Identification:
- Agent responses don’t match intended personality
- Inconsistent tone or behavior across conversations
- Generic responses without business context
- Setup progress shows system prompt as incomplete
2
Verification Process
Configuration Check:
- Navigate to Agent Management > System Prompt
- Verify all required fields are completed
- Check that prompt reflects desired agent behavior
- Ensure business context and role are clearly defined
3
Configuration Optimization
Improvement Actions:
- Complete all sections of system prompt configuration
- Add specific business context and company information
- Define clear role and expertise areas
- Test changes in playground before deployment
Credit and Account Issues
Credits Exhausted
Problem Recognition:
- Agent stops responding to new messages
- Dashboard shows zero or negative credit balance
- Users see “agent unavailable” messages
- Check credit balance in billing dashboard
- Purchase credit top-up if on paid plan
- Upgrade plan for automatic credit renewal
- Monitor usage to prevent future exhaustion
Network Connectivity
Connection Issues:
- Intermittent agent responses
- Slow response times or timeouts
- Dashboard loading problems
- Check internet connection stability
- Try accessing from different network
- Clear browser cache and cookies
- Disable VPN or proxy if in use
Integration Problems
Code Placement Issues
Incorrect Script Placement
Incorrect Script Placement
Common Mistakes:Verification:
- Script placed in
<head>section instead of before</body> - Script loaded after page content is already rendered
- Multiple script tags causing conflicts
- Script placement inside other elements or containers
- View page source to confirm script placement
- Check browser developer tools for script loading
- Test widget appearance on live website
- Verify functionality across different pages
Script Loading Issues
Script Loading Issues
Loading Problems:
- Widget doesn’t appear on website
- JavaScript errors in browser console
- Partial widget loading or broken functionality
- Widget appears but doesn’t respond to clicks
- Check browser developer console for errors
- Verify script URL is correct and accessible
- Ensure no conflicting JavaScript on page
- Test with ad blockers and extensions disabled
- Validate HTML structure and syntax
Browser Cache Issues
1
Cache-Related Problems
Problem Symptoms:
- Old widget version appears despite updates
- Configuration changes not reflected on website
- Widget functionality inconsistent across visits
- Outdated styling or appearance persists
2
Cache Clearing Process
Browser Cache Clearing:
- Chrome: Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)
- Firefox: Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)
- Safari: Develop menu > Empty Caches
- Edge: Ctrl+Shift+Delete
- Clear cookies for your domain
- Disable browser extensions temporarily
- Try incognito/private browsing mode
- Test on different browsers
3
CDN and Server Cache
Server-Side Solutions:
- Clear CDN cache if using content delivery network
- Flush server-side caches (WordPress, etc.)
- Update script version or add cache-busting parameters
- Contact hosting provider for assistance
Console Errors
JavaScript Errors
Common Error Types:
- “Script not found” or 404 errors
- “Permission denied” or CORS errors
- “Function not defined” or reference errors
- “Network error” or timeout issues
Error Resolution
Debugging Process:
- Open browser developer tools (F12)
- Check Console tab for error messages
- Note specific error descriptions and line numbers
- Take screenshots of errors for support
Mobile Compatibility
Mobile Display Issues
Mobile Display Issues
Common Problems:
- Widget not appearing on mobile devices
- Poor responsive design or layout issues
- Touch interaction problems
- Performance issues on mobile networks
- Test on actual mobile devices, not just desktop simulation
- Check both iOS and Android devices
- Verify touch interactions work properly
- Test on different screen sizes and orientations
Mobile Optimization
Mobile Optimization
Performance Improvements:
- Ensure widget is mobile-responsive
- Check loading speed on mobile networks
- Verify widget size appropriate for mobile screens
- Test with different mobile browsers
- Adjust widget position for mobile layout
- Optimize widget size for touch interfaces
- Consider mobile-specific styling options
- Test viewport and zoom compatibility
Performance Issues
Response Speed Problems
1
Slow Response Times
Performance Indicators:
- Agent takes more than 10 seconds to respond
- Users experience long waiting periods
- Timeouts or incomplete responses
- Inconsistent response timing
2
Agent Health Assessment
System Check:
- Check agent health status in dashboard
- Review system performance metrics
- Verify knowledge base index health
- Monitor real-time performance indicators
3
Optimization Actions
Performance Improvements:
- Optimize knowledge base content organization
- Reduce system prompt complexity
- Check for network connectivity issues
- Consider reducing concurrent user load
Message Quality Issues
Poor Response Quality
Quality Problems:
- Inaccurate or irrelevant responses
- Inconsistent personality or tone
- Repetitive or generic answers
- Poor grammar or formatting
Quality Improvement
Enhancement Strategies:
- Review and refine system prompt configuration
- Update and organize knowledge base content
- Test responses in playground environment
- Gather user feedback for optimization
Session Limits
Concurrent User Limits
Concurrent User Limits
Capacity Issues:
- Users unable to start new conversations
- “Agent busy” messages during peak times
- Degraded performance with multiple users
- Session queue delays and waiting times
- Monitor concurrent session limits
- Check account plan limitations
- Consider upgrading for higher capacity
- Implement user queue management
Resource Management
Resource Management
Optimization Strategies:
- Analyze usage patterns and peak times
- Optimize conversation efficiency
- Consider load balancing strategies
- Plan capacity for expected traffic
Server Status Issues
1
Platform Status Verification
Service Health Check:
- Check Ravvio platform operational status
- Verify system maintenance schedules
- Review service disruption notifications
- Monitor real-time system health indicators
2
Status Communication
Information Sources:
- Dashboard system status indicators
- Email notifications for service issues
- Support team communications
- Platform status page updates
3
Issue Escalation
When to Contact Support:
- Persistent performance issues
- Unresolved technical problems
- Service disruptions affecting business
- Integration failures requiring assistance
General Troubleshooting Steps
Systematic Problem Resolution
Initial Assessment
Problem Identification:
- Document specific symptoms and error messages
- Note when the problem started occurring
- Identify affected users or functionality
- Check if issue is consistent or intermittent
Basic Solutions
First-Line Fixes:
- Refresh page and clear browser cache
- Try different browser or device
- Check internet connection stability
- Verify account status and credit balance
Advanced Diagnostics
Technical Investigation
Technical Investigation
Detailed Analysis:
- Review browser developer console for errors
- Check network tab for failed requests
- Examine configuration settings and changes
- Test in playground environment
- Screenshot error messages
- Note exact error text and codes
- Document steps to reproduce issue
- Record browser and system information
Escalation Criteria
Escalation Criteria
When to Contact Support:
- Issue persists after following troubleshooting steps
- Problem affects business operations or revenue
- Technical error messages are unclear
- Multiple users report the same issue
- Detailed problem description
- Steps already attempted to resolve
- Screenshots or recordings of issue
- Account information and affected features
Documentation: Keep records of troubleshooting steps and solutions for future reference and team knowledge sharing.
Preventive Maintenance: Regular monitoring and proactive maintenance help prevent many common issues from occurring.
Data Safety: Always backup important configuration and data before making significant changes during troubleshooting.