VICIdial Error: Agent Screen Blank — Cause & Fix

Error Summary

Error Message

Agent Screen Blank

Severity

Critical

Component

Web

What Causes This Error

The VICIdial agent interface displays a blank white or black screen. Causes include: VICIdial web server (Apache/Nginx) error, PHP processing error, database connection failure, browser JavaScript error, session timeout, or the agent's IP being blocked by fail2ban after multiple login failures.

How to Fix It

  1. 1
    Check browser console (F12) for JavaScript errors
  2. 2
    Check Apache error log: sudo tail -50 /var/log/apache2/error.log
  3. 3
    Check PHP errors: sudo tail -50 /var/log/php_errors.log
  4. 4
    Check MySQL connection: mysql -u cron -ptest -e 'SELECT 1'
  5. 5
    Check if agent IP is blocked: sudo fail2ban-client status apache-auth
  6. 6
    If blocked, unblock IP: sudo fail2ban-client set apache-auth unbanip AGENT_IP
  7. 7
    Restart Apache if PHP processing is failing: sudo systemctl restart apache2
  8. 8
    Have agent clear browser cache and try incognito mode

How to Prevent It

Implement uptime monitoring for the VICIdial web interface. Configure fail2ban whitelist for office IP ranges. Monitor Apache error logs daily. Keep browser recommendations documented for agents.

Critical Phone Login Not Active Web Warning Screen Pop Blank Web Warning API Authentication Failed Web

Still Stuck?

ViciStack's free 30-day support plan includes unlimited live VICIdial troubleshooting. If you can't resolve this error with the steps above, our engineers will connect to your system and fix it directly — no support tickets, no hourly billing.

Get Free VICIdial Support →

Frequently Asked Questions

What causes the VICIdial "Agent Screen Blank" error?
The VICIdial agent interface displays a blank white or black screen. Causes include: VICIdial web server (Apache/Nginx) error, PHP processing error, database connection failure, browser JavaScript error, session timeout, or the agent's IP being blocked by fail2ban after multiple login failures.
How do I fix the VICIdial "Agent Screen Blank" error?
Check browser console (F12) for JavaScript errors Then: Check Apache error log: sudo tail -50 /var/log/apache2/error.log Then: Check PHP errors: sudo tail -50 /var/log/php_errors.log Then: Check MySQL connection: mysql -u cron -ptest -e 'SELECT 1' Then: Check if agent IP is blocked: sudo fail2ban-client status apache-auth Then: If blocked, unblock IP: sudo fail2ban-client set apache-auth unbanip AGENT_IP Then: Restart Apache if PHP processing is failing: sudo systemctl restart apache2 Then: Have agent clear browser cache and try incognito mode
How can I prevent the "Agent Screen Blank" error in VICIdial?
Implement uptime monitoring for the VICIdial web interface. Configure fail2ban whitelist for office IP ranges. Monitor Apache error logs daily. Keep browser recommendations documented for agents.