Troubleshooting

This guide helps you diagnose and resolve common issues with Agora. Find solutions to installation problems, scanning errors, authentication issues, and performance problems.

Common Issues Quick Reference

Installation and Startup

Problem	Symptoms	Solution
App won't start	Application crashes on launch	Check system requirements
License error on startup	"License required" message	Verify license status
Authentication fails	Cannot log in to QualiBooth account	Reset authentication
Browser engine missing	"Browser not found" error	Browser view problems

Scanning Problems

Problem	Symptoms	Solution
Scans fail to start	Scan button doesn't work	Website scanning problems
Scans timeout	Pages never finish scanning	Scan failures
Network errors	"Cannot connect" messages	Network and connectivity issues
Authentication required	Pages require login	Configure website authentication

Installation and Startup Issues

System Requirements

Minimum Requirements Check

Before troubleshooting, verify your system meets requirements:

Operating System:

• Windows 10 (build 1809) or later
• macOS 10.14 (Mojave) or later

Hardware:

• 4GB RAM minimum (8GB recommended)
• 500MB available disk space
• Internet connection for licensing and AI features

Software Dependencies:

• .NET Framework 4.7.2+ (Windows)
• Modern Chromium browser engine

System Diagnostic Steps

1. Check OS Version: Verify you're running a supported operating system version
2. Available Memory: Ensure sufficient RAM is available (close other applications)
3. Disk Space: Verify adequate free disk space on system drive
4. Network Connection: Confirm internet connectivity to *.qualibooth.com

Application Launch Problems

Windows Launch Issues

"App can't run on this PC":

1. Verify Windows 10/11 compatibility
2. Check if you're running 32-bit vs 64-bit (use 64-bit installer)
3. Try running installer as Administrator
4. Temporarily disable antivirus during installation

DLL or .NET Errors:

1. Install latest .NET Framework from Microsoft
2. Run Windows Update to ensure system components are current
3. Try installing Visual C++ Redistributables
4. Restart system and try again

macOS Launch Issues

"App is damaged and can't be opened":

# Remove quarantine attribute
xattr -cr /Applications/Agora.app

Gatekeeper blocking execution:

1. Go to System Preferences > Security & Privacy
2. Click "Open Anyway" when prompted
3. Or temporarily disable Gatekeeper:

sudo spctl --master-disable

Authentication Problems

Login and Session Issues

Authentication Browser Problems

Browser window doesn't appear:

1. Check for window behind other applications
2. Look in taskbar/dock for hidden window
3. Try clicking Login button again
4. Restart Agora and try again

Browser stuck loading:

1. Wait 60 seconds for timeout
2. Close browser window manually
3. Click Login again
4. Check network connectivity to QualiBooth servers

SSL/Certificate errors:

1. Check system date and time are correct
2. Update root certificates on your system
3. Try disabling antivirus SSL scanning temporarily
4. Contact IT department about corporate firewalls

Session Management

Frequent logouts:

• Sessions expire after 30 days of inactivity
• Check if system time is synchronized
• Verify license hasn't expired
• Clear application cache and re-authenticate

"Auth browser closed" message:

• You or system closed authentication browser before completion
• Simply click Login button again to restart process
• Ensure no popup blockers are interfering

License Issues

License Verification Problems

"License required" after successful login:

1. Check License Assignment:

   • Log into QualiBooth Portal
   • Verify Agora license is assigned to your account
   • Check license expiration date

2. Account/Organization Issues:

   • Ensure you're in the correct organization
   • Verify your role has appropriate permissions
   • Contact organization administrator

3. Sync Delay:

   • Wait 5-10 minutes for license changes to propagate
   • Close and restart Agora
   • Try logging out and back in

AI features not available:

• Verify AI license is assigned in QualiBooth Portal
• Check AI license hasn't expired
• Ensure internet connectivity for AI service access
• Contact administrator about AI license availability

License Troubleshooting Steps

1. Verify Portal Access:

   • Can you log into QualiBooth Portal successfully?
   • Do you see license information in your profile?
   • Are licenses showing as active and current?

2. Network Connectivity:

   • Test connection to *.qualibooth.com
   • Check corporate firewall isn't blocking license verification
   • Try from different network if possible

3. Clear License Cache:

   • Close Agora completely
   • Clear application data/cache
   • Restart and re-authenticate

Scanning and Testing Issues

Website Scanning Problems

Scan Failures

Scans won't start:

1. Check Website Configuration:

   • Verify URL is accessible and correct
   • Ensure URL includes protocol (https:// or http://)
   • Test URL in regular browser first

2. Network Connectivity:

   • Verify internet connection
   • Check if website is accessible from your network
   • Test with simple websites like Google.com

3. Authentication Issues:

   • Configure authentication using the authentication workflow if website requires it
   • Set up custom headers for API authentication
   • Check if website blocks automated access

Pages timeout during scanning:

1. Increase Timeout Values:

   • Go to Settings > Scanning
   • Increase page timeout from 30s to 60s or more
   • Enable extended wait for dynamic content

2. Optimize Page Loading:

   • Disable page scrolling if not needed
   • Reduce viewport size for faster rendering
   • Enable headless mode for better performance

3. Network Optimization:

   • Check for slow network connection
   • Reduce concurrent scans if network is limited
   • Consider scanning during off-peak hours

Accessibility Scanning Issues

Inconsistent or missing results:

1. Dynamic Content Issues:

   • Enable page scrolling in scanning settings
   • Increase delay after page load
   • Test with visual scanning mode to see what's being captured

2. JavaScript-Heavy Sites:

   • Allow more time for JavaScript execution
   • Enable "wait for network idle" option
   • Test specific pages individually first

3. Authentication Protected Content:

   • Set up proper authentication using the authentication workflow
   • Test authentication with browser view first
   • Ensure authentication persists throughout scan

Browser View Problems

Browser Loading Issues

Pages won't load in browser view:

1. Check URL is correctly formatted
2. Verify network connectivity
3. Try loading in external browser first
4. Check if site blocks embedded browsers

Browser crashes or freezes:

1. Reduce browser window size
2. Close other applications to free memory
3. Restart Agora
4. Check for system updates

Real-Time Scanning Problems

Violations not highlighting:

1. Ensure accessibility scanning is enabled
2. Check if page has finished loading completely
3. Try refreshing the page
4. Verify WCAG rules are enabled in settings

Performance Issues

Slow Performance

Application Sluggishness

Agora responds slowly:

1. Memory Management:

   • Close unnecessary applications
   • Restart Agora to clear memory leaks
   • Reduce concurrent operations

2. Database Optimization:

   • Clear old scan results if database is large
   • Compact/optimize database through settings
   • Consider archiving old data

3. Resource Allocation:

   • Reduce concurrent scan limit
   • Lower scan queue size
   • Disable background processing if not needed

Scanning Performance

Scans take too long:

1. Enable Performance Optimizations:

   • Use headless mode for faster scanning
   • Disable page scrolling if not needed
   • Reduce page timeout values

2. Resource Management:

   • Increase concurrent scan limit (if system can handle it)
   • Use faster network connection
   • Close other bandwidth-intensive applications

3. Content Optimization:

   • Start with key pages before scanning entire site
   • Skip non-essential pages in large sites
   • Use sitemap filtering to focus on important content

Memory and Storage Issues

High Memory Usage

Agora using too much memory:

1. Reduce concurrent scans
2. Clear scan history regularly
3. Restart application periodically
4. Close browser view when not needed

Disk Space Problems

Running out of disk space:

1. Clean up old reports in export directory
2. Clear cached scan data
3. Reduce screenshot quality in settings
4. Archive old website data

Network and Connectivity Issues

Connection Problems

General Network Issues

Cannot connect to websites:

1. Basic Connectivity:

   • Test internet connection with other applications
   • Try accessing websites in regular browser
   • Check DNS resolution

2. Proxy Configuration:

   • Configure proxy settings in Agora if needed
   • Test with proxy temporarily disabled
   • Verify proxy credentials are correct

3. Firewall Issues:

   • Check corporate firewall isn't blocking Agora
   • Ensure required domains are whitelisted
   • Test from different network if possible

QualiBooth Service Connectivity

Cannot connect to QualiBooth services:

1. Service Status:

   • Check QualiBooth status page for outages
   • Try accessing QualiBooth Portal in browser
   • Test connectivity to auth.qualibooth.com

2. DNS and Routing:

   • Try using different DNS servers (8.8.8.8, 1.1.1.1)
   • Check if your ISP is blocking access
   • Use VPN to test from different location

SSL and Security Issues

Certificate Problems

SSL certificate errors:

1. Check system date and time are correct
2. Update root certificate store
3. Temporarily disable SSL verification for testing
4. Contact IT about corporate certificate policies

Corporate security blocking:

1. Work with IT to whitelist required domains
2. Configure proxy/firewall exceptions
3. Use corporate certificate bundle if required
4. Consider using different network for testing

AI Features Issues

AI License and Connectivity

AI Features Not Working

Screen reader simulation unavailable:

1. License Verification:

   • Check AI license status in QualiBooth Portal
   • Verify license hasn't expired
   • Contact administrator about AI license assignment

2. Service Connectivity:

   • Verify internet connection to AI services
   • Check corporate firewall allows AI service access
   • Test with simpler AI features first

AI analysis takes too long:

1. Check network connection quality
2. Try with smaller/simpler pages first
3. Reduce analysis scope or complexity
4. Contact support if consistent delays occur

Error Messages and Codes

Common Error Messages

Authentication Errors

"Authentication failed":

• Verify QualiBooth Portal credentials
• Check account status isn't suspended
• Try password reset if needed

"License verification failed":

• Check internet connectivity
• Verify license is active in portal
• Contact support for license issues

Scanning Errors

"Page load timeout":

• Increase timeout in scanning settings
• Check if page loads in regular browser
• Verify network connectivity to target site

"Access denied":

• Configure authentication for protected sites using the authentication workflow
• Check if site blocks automated access
• Verify URL is correct and accessible

"Browser engine error":

• Restart Agora to reset browser engine
• Check for available system updates
• Reinstall Agora if browser engine is corrupted

System Errors

"Insufficient memory":

• Close other applications to free RAM
• Reduce concurrent scan operations
• Restart system if memory leak suspected

"Disk space full":

• Clean up old reports and cached data
• Move export directory to drive with more space
• Archive or delete old scan results

Getting Additional Help

Self-Service Resources

Built-in Diagnostics

System Information Report:

1. Go to Help > System Information
2. Review system configuration and status
3. Look for red warnings or error indicators
4. Use report when contacting support

Connection Testing:

1. Use Help > Test Connectivity
2. Verify all required services are accessible
3. Check for network or firewall issues
4. Document any failed connection tests

Log Files and Debugging

Accessing Log Files:

• Windows: %APPDATA%/Agora/logs/
• macOS: ~/Library/Logs/Agora/

Debug Mode:

1. Enable debug mode in Advanced Settings
2. Reproduce the issue
3. Collect log files
4. Disable debug mode when done

Contacting Support

Before Contacting Support

Gather this information:

1. System Information: OS version, Agora version, system specs
2. Error Details: Exact error messages, when they occur
3. Steps to Reproduce: What you were doing when the problem occurred
4. Log Files: Recent log files (enable debug mode if possible)
5. Screenshots: Visual evidence of the problem

Support Channels

1. QualiBooth Portal: Submit support ticket through portal
2. Documentation: Check this documentation for solutions
3. Community Forums: Search community discussions
4. Direct Contact: Use contact information provided by your organization

Escalation Process

For urgent issues:

1. Mark support ticket as "High Priority"
2. Include business impact in ticket description
3. Reference any compliance deadlines affected
4. Provide complete system information and logs

Remember to always test solutions in a safe environment before applying to production systems.

Ready to explore frequently asked questions? Continue to FAQ.