Skip to main content

​
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

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
Diagnostic Steps:
  1. Navigate to Knowledge Base section in dashboard
  2. Verify documents are listed and status shows “Ready”
  3. Check document processing status and error messages
  4. Confirm file formats are supported (PDF, DOCX, TXT, CSV, JSON, MD, HTML)
Solutions:
  • 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
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
Troubleshooting Process:
  1. Check index health status in dashboard
  2. Review error logs and processing messages
  3. Verify document integrity and content quality
  4. Attempt to reprocess problematic documents
Resolution Steps:
  • 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
Immediate Solutions:
  • 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
Troubleshooting Steps:
  • 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

Common Mistakes:
  • 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
Correct Implementation:
<!-- Other page content -->

<!-- Place Ravvio script before closing body tag -->
<script src="your-ravvio-widget-script.js"></script>
</body>
</html>
Verification:
  • 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
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
Resolution Steps:
  1. Check browser developer console for errors
  2. Verify script URL is correct and accessible
  3. Ensure no conflicting JavaScript on page
  4. Test with ad blockers and extensions disabled
  5. 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
Additional Steps:
  • 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

Common Problems:
  • Widget not appearing on mobile devices
  • Poor responsive design or layout issues
  • Touch interaction problems
  • Performance issues on mobile networks
Mobile Testing:
  • 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
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
Configuration Adjustments:
  • 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

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
Immediate Solutions:
  • Monitor concurrent session limits
  • Check account plan limitations
  • Consider upgrading for higher capacity
  • Implement user queue 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

Detailed Analysis:
  • Review browser developer console for errors
  • Check network tab for failed requests
  • Examine configuration settings and changes
  • Test in playground environment
Data Collection:
  • Screenshot error messages
  • Note exact error text and codes
  • Document steps to reproduce issue
  • Record browser and system information
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
Support Information to Provide:
  • 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.