ViciDial Agent Screen Blank or Not Loading — PHP & Browser Fixes

Master the complete diagnostic and resolution workflow for ViciDial agent screen failures, including server-side PHP debugging, database verification, browser compatibility checks, and production deployment fixes.

Prerequisites

Before starting, ensure you have:

• SSH access to your ViciDial server with root or sudo privileges
• Basic familiarity with Linux command line and ViciDial architecture
• Access to MySQL/MariaDB client tools
• A test agent account (non-production preferred initially)
• Knowledge of your ViciDial version (check: cat /etc/asterisk/vicidial_version.txt)
• Apache/Nginx web server logs accessible (typically /var/log/apache2/ or /var/log/nginx/)
• PHP CLI access for testing (php -v should return a version)

Understanding the ViciDial Agent Screen Architecture

What Loads When an Agent Logs In

When an agent navigates to /agc/vicidial.php, the following occurs:

1. PHP session validation against the vicidial_users table
2. AJAX polling to /agc/vicidial_ajax.php for call data
3. JavaScript initialization loading /agc/jquery.js and related files
4. Browser websocket or long-polling connection to asterisk events
5. Database queries to vicidial_log, vicidial_campaign, and related tables

A blank screen typically means one or more of these steps is failing silently.

Common Failure Points

• PHP execution timeout during database queries
• Missing or corrupt session data in Redis/memcached or file system
• Database connection failure or permission issues
• JavaScript errors preventing DOM rendering
• CORS/HTTPS mixed content issues in modern browsers
• Apache/PHP-FPM process crashes or memory exhaustion
• Stale cache serving outdated or broken HTML

Step 1: Check Apache and PHP Error Logs

Real-Time Log Monitoring

The fastest way to identify the issue is watching error logs as an agent logs in:

# Terminal 1: Watch Apache error log
tail -f /var/log/apache2/error.log | grep -i php

# Terminal 2: Watch Apache access log
tail -f /var/log/apache2/access.log | grep vicidial.php

# Terminal 3: Watch PHP-FPM error log (if using FPM)
tail -f /var/log/php-fpm.log

Now have the agent login and attempt to load the agent screen.

Check for PHP Syntax Errors

Even a single PHP syntax error will cause a blank screen:

# Check vicidial.php for syntax errors
php -l /var/www/html/agc/vicidial.php

# Check all PHP files in the agc directory
for file in /var/www/html/agc/*.php; do php -l "$file"; done

If you see Parse error output, the filename and line number are displayed.

Enable PHP Debug Output (Temporary)

Add debug headers to /var/www/html/agc/vicidial.php at the very top:

<?php
error_reporting(E_ALL);
ini_set('display_errors', '1');
ini_set('log_errors', '1');
ini_set('error_log', '/var/log/php-debug.log');

// Rest of vicidial.php code follows...

Then reload the agent screen and check the debug log:

tail -50 /var/log/php-debug.log

Remove these debug lines before returning to production.

Step 2: Verify Database Connectivity and Permissions

Test MySQL Connection from PHP

Create a test script at /var/www/html/test_db.php:

<?php
// Database connection test
$db_host = 'localhost';
$db_user = 'cron';
$db_pass = 'YOUR_CRON_PASSWORD'; // Check /etc/asterisk/astguiclient.conf
$db_name = 'asterisk';

try {
    $mysqli = new mysqli($db_host, $db_user, $db_pass, $db_name);
    
    if ($mysqli->connect_error) {
        die("Connection failed: " . $mysqli->connect_error);
    }
    
    echo "Database connection: SUCCESS\n";
    
    // Test critical tables
    $tables = array('vicidial_users', 'vicidial_log', 'vicidial_campaign', 'vicidial_carrier');
    
    foreach ($tables as $table) {
        $result = $mysqli->query("SELECT COUNT(*) FROM $table");
        if ($result) {
            $row = $result->fetch_row();
            echo "Table $table: OK (" . $row[0] . " rows)\n";
        } else {
            echo "Table $table: FAILED - " . $mysqli->error . "\n";
        }
    }
    
    // Test session table
    $result = $mysqli->query("SELECT COUNT(*) FROM session_tbl");
    if ($result) {
        echo "Session table: OK\n";
    } else {
        echo "Session table issue (non-critical if using file storage)\n";
    }
    
    $mysqli->close();
} catch (Exception $e) {
    die("Error: " . $e->getMessage());
}
?>

Access this from your browser:

http://YOUR_VICIDIAL_IP/test_db.php

Or from command line:

php /var/www/html/test_db.php

Check Database Permissions

Log into MySQL and verify the cron user has proper permissions:

mysql -u root -p

-- Check current grants
SHOW GRANTS FOR 'cron'@'localhost';

-- If permissions are missing, grant them:
GRANT ALL PRIVILEGES ON asterisk.* TO 'cron'@'localhost' IDENTIFIED BY 'PASSWORD';
FLUSH PRIVILEGES;

-- Verify vicidial_users table has your test user
SELECT user_id, user, pass, user_level, active FROM vicidial_users 
WHERE user = 'YOURTESTUSER' LIMIT 1;

Test Session Table Access

If ViciDial uses MySQL session storage:

-- Check if sessions table exists and is writable
SELECT TABLE_NAME FROM information_schema.TABLES 
WHERE TABLE_SCHEMA='asterisk' AND TABLE_NAME='session_tbl';

-- Clear stale sessions (optional)
DELETE FROM session_tbl WHERE expire < UNIX_TIMESTAMP();

Step 3: Check PHP Configuration and Resource Limits

Verify PHP Settings

Create /var/www/html/phpinfo.php:

<?php phpinfo(); ?>

Check critical settings via CLI:

php -r "echo 'max_execution_time: ' . ini_get('max_execution_time') . \"\n\"; 
echo 'memory_limit: ' . ini_get('memory_limit') . \"\n\"; 
echo 'max_input_time: ' . ini_get('max_input_time') . \"\n\";"

Recommended ViciDial PHP Configuration

Edit /etc/php/7.4/fpm/php.ini (or your PHP version):

max_execution_time = 300
max_input_time = 300
memory_limit = 512M
post_max_size = 100M
upload_max_filesize = 100M
default_socket_timeout = 60

; Logging
display_errors = Off
log_errors = On
error_log = /var/log/php-error.log

; Session handling
session.save_handler = files
session.save_path = "/var/lib/php/sessions"
session.gc_maxlifetime = 86400
session.cookie_httponly = 1
session.cookie_secure = 1

Ensure session directory exists and is writable:

mkdir -p /var/lib/php/sessions
chown www-data:www-data /var/lib/php/sessions
chmod 700 /var/lib/php/sessions

Restart PHP-FPM or Apache

# If using PHP-FPM
systemctl restart php7.4-fpm

# If using mod_php with Apache
systemctl restart apache2

Step 4: Browser Developer Tools Inspection

Modern agents frequently encounter blank screens due to JavaScript errors or CORS issues.

Open Browser Console

1. In Chrome/Firefox, press F12
2. Click the Console tab
3. Look for red error messages

Common Browser Errors and Fixes

Error: "Mixed Content: The page at 'https://...' was loaded over HTTPS, but..."

Solution: Force HTTPS in Apache vhost:

# /etc/apache2/sites-available/vicidial.conf
<VirtualHost *:443>
    ServerName your.vicidial.domain
    
    # Force HTTPS
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
    
    # CORS headers for AJAX
    Header set Access-Control-Allow-Origin "*"
    Header set Access-Control-Allow-Methods "GET, POST, OPTIONS"
    Header set Access-Control-Allow-Headers "Content-Type, Authorization"
    
    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/your_cert.crt
    SSLCertificateKeyFile /etc/ssl/private/your_key.key
</VirtualHost>

Error: "Cannot read property 'X' of undefined"

Solution: This usually means JavaScript initialization failed. Check:

# Verify jQuery and JavaScript files exist
ls -la /var/www/html/agc/jquery.js
ls -la /var/www/html/agc/vicidial*.js
ls -la /var/www/html/agc/jquery_plugins/

Error: "WebSocket connection to 'wss://...' failed"

Solution: This is non-critical for basic functionality but indicates asterisk event connection failure. Check:

# Verify asterisk is running
systemctl status asterisk

# Check asterisk listening ports
netstat -tlnp | grep asterisk | head -10

Step 5: Clear Browser Cache and Session Data

Clear ViciDial Session Cache

ViciDial stores session data in multiple places:

# Clear file-based sessions
rm -rf /var/lib/php/sessions/*

# Clear Redis cache (if used)
redis-cli FLUSHDB

# Clear Apache cache (if mod_cache is enabled)
rm -rf /var/cache/apache2/*

Clear Browser Cache Programmatically

Add cache-busting headers to /var/www/html/agc/vicidial.php:

<?php
// Add at the very top, before any output
header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0');
header('Cache-Control: post-check=0, pre-check=0', false);
header('Pragma: no-cache');
header('Expires: Thu, 01 Jan 1970 00:00:00 GMT');

// Rest of code...
?>

Instruct agents to:

1. Chrome: Press Ctrl+Shift+Delete to open Clear Browsing Data
2. Firefox: Press Ctrl+Shift+Delete
3. Select "All time" and "Cookies and cached images"
4. Restart browser completely

Step 6: Check ViciDial-Specific Configuration Files

Verify Web Server Configuration

# Check vicidial web server root
grep -r "DocumentRoot" /etc/apache2/sites-enabled/ | grep vicidial

# Typical path:
ls -la /var/www/html/agc/vicidial.php

Review vicidial.conf Settings

grep -E "(session|cache|timeout)" /etc/asterisk/vicidial.conf

Check for database connection parameters:

cat /etc/asterisk/astguiclient.conf | grep -E "(db_host|db_user|db_pass|db_name)"

Example output:

db_host=localhost
db_name=asterisk
db_user=cron
db_pass=1234

Verify Agent User Settings in Database

mysql -u cron -p -e "USE asterisk; SELECT user_id, user, pass, user_level, active, phone_login, current_status FROM vicidial_users WHERE user='TESTUSER';"

Critical fields:

• active must be Y
• user_level must be >= 1
• phone_login can be empty for web-only agents

Step 7: Test Agent Screen with Curl

Simulate Browser Request

# First, get a session cookie
COOKIE=$(curl -s -c /tmp/cookie.txt \
  -d "user=testuser&pass=testpass&login=Login" \
  http://YOUR_VICIDIAL_IP/vicidial/admin.php | grep -o "PHPSESSID=[^;]*")

# Then request the agent screen
curl -s -b /tmp/cookie.txt \
  -H "X-Requested-With: XMLHttpRequest" \
  "http://YOUR_VICIDIAL_IP/agc/vicidial.php" | head -100

If you see HTML content, PHP is executing. If blank, PHP is failing.

Test AJAX Endpoint

curl -s -b /tmp/cookie.txt \
  "http://YOUR_VICIDIAL_IP/agc/vicidial_ajax.php?function=getUserStatus" | head -50

Step 8: Check for PHP Memory and Timeout Issues

Monitor System Resources During Login

In one terminal, watch system load:

watch -n 1 'free -h; echo "---"; ps aux | grep -E "(apache|php|mysql)" | grep -v grep'

In another, have the agent log in.

Check Apache Process Status

# View Apache process limits
ps aux | grep apache2 | head -3

# Check for zombie processes
ps aux | grep defunct

# View Apache module status
apache2ctl -M | grep -E "(php|mpm)"

Increase Apache Workers (If Needed)

Edit /etc/apache2/mods-enabled/mpm_prefork.conf:

<IfModule mpm_prefork_module>
    StartServers             10
    MinSpareServers          5
    MaxSpareServers          15
    MaxRequestWorkers        256
    MaxConnectionsPerChild   0
</IfModule>

Restart:

systemctl restart apache2

Step 9: Database Query Performance Issues

Identify Slow Queries

Enable MySQL slow query log:

mysql -u root -p -e "SET GLOBAL slow_query_log = 'ON'; SET GLOBAL long_query_time = 2;"

Then have the agent login and check:

tail -50 /var/log/mysql/slow.log | grep vicidial

If you see queries taking > 2 seconds, optimization is needed.

Check Active Queries During Login

# In MySQL, watch active connections
SHOW PROCESSLIST;

# Look for long-running queries
SHOW PROCESSLIST WHERE Time > 5;

Optimize Critical Tables

-- Analyze tables for query optimization
ANALYZE TABLE vicidial_users;
ANALYZE TABLE vicidial_log;
ANALYZE TABLE vicidial_campaign;

-- Check and repair if needed
CHECK TABLE vicidial_users;
REPAIR TABLE vicidial_users;

-- View index statistics
SHOW INDEX FROM vicidial_users;

Step 10: ViciDial Admin Console Verification

Verify Agent in Admin

Log into the ViciDial admin panel at /vicidial/admin.php:

1. Click Users → Agent Users
2. Search for your test agent
3. Verify:
   • Active status is Y
   • User level is >= 1
   • Campaign is assigned
   • Phone extension is valid

Check Campaign Configuration

mysql -u cron -p -e "USE asterisk; SELECT campaign_id, campaign_name, active, lead_filter_id FROM vicidial_campaign WHERE active='Y' LIMIT 5;"

Restart ViciDial Services

# Restart Asterisk
systemctl restart asterisk

# Restart Apache
systemctl restart apache2

# Restart MySQL (if changes were made)
systemctl restart mysql

Allow 30 seconds for services to fully start, then test agent login.

Step 11: Log File Analysis

Check ViciDial Application Log

# Most recent ViciDial-related entries
grep -i "agent\|login\|error" /var/log/asterisk/messages | tail -50

# Real-time monitoring
tail -f /var/log/asterisk/messages | grep -i agent

Check Apache Access Logs for Agent Screen Requests

# Show all vicidial.php requests
grep "vicidial.php" /var/log/apache2/access.log | tail -20

# Show requests with errors (4xx/5xx)
grep "vicidial.php" /var/log/apache2/access.log | grep -E "4[0-9]{2}|5[0-9]{2}" | tail -20

Parse Apache Error Codes

# Count error codes
grep "vicidial.php" /var/log/apache2/error.log | \
  sed 's/.*\[error\]//' | sort | uniq -c | sort -rn | head -10

Step 12: Production Deployment and Prevention

Create a Monitoring Script

Save as /usr/local/bin/vicidial_health_check.sh:

#!/bin/bash

echo "=== ViciDial Health Check ==="
echo "Time: $(date)"

# Check services
echo -e "\n--- Service Status ---"
systemctl is-active asterisk && echo "Asterisk: OK" || echo "Asterisk: FAILED"
systemctl is-active apache2 && echo "Apache: OK" || echo "Apache: FAILED"
systemctl is-active mysql && echo "MySQL: OK" || echo "MySQL: FAILED"

# Check database connectivity
echo -e "\n--- Database Connectivity ---"
mysql -u cron -p$DB_PASS -e "SELECT 1" >/dev/null 2>&1 && echo "MySQL Connection: OK" || echo "MySQL Connection: FAILED"

# Check PHP syntax
echo -e "\n--- PHP Syntax Check ---"
php -l /var/www/html/agc/vicidial.php | grep -q "No syntax errors" && echo "vicidial.php: OK" || echo "vicidial.php: FAILED"

# Check disk space
echo -e "\n--- Disk Space ---"
df -h / | awk 'NR==2 {print "Root: " $5 " used"}'
df -h /var | awk 'NR==2 {print "/var: " $5 " used"}'

# Check logs for errors
echo -e "\n--- Recent Errors ---"
tail -5 /var/log/apache2/error.log

echo -e "\n--- End Health Check ---"

Make executable and schedule:

chmod +x /usr/local/bin/vicidial_health_check.sh

# Run via cron daily
echo "0 2 * * * /usr/local/bin/vicidial_health_check.sh" | crontab -

Set Up Automated Error Alerts

Create /etc/rsyslog.d/vicidial-alert.conf:

# Alert on PHP errors in ViciDial
:msg,contains,"PHP Fatal" /var/log/vicidial-alerts.log
& stop

:msg,contains,"PHP Warning" /var/log/vicidial-alerts.log
& stop

Restart rsyslog:

systemctl restart rsyslog

Document Configuration for Team

Create a runbook at /var/www/html/TROUBLESHOOTING.md:

# ViciDial Agent Screen Troubleshooting Runbook

## Quick Fix Checklist
1. [ ] Clear browser cache (Ctrl+Shift+Delete)
2. [ ] Verify agent is active in admin panel
3. [ ] Check /var/log/apache2/error.log for PHP errors
4. [ ] Restart Apache: systemctl restart apache2
5. [ ] Test database connection: php /var/www/html/test_db.php

## Escalation
- Database issue: Check /var/log/mysql/error.log
- Asterisk issue: Check asterisk -rx "core show channels"
- Network issue: Check browser console (F12)

## Contact: [Your Contact Info]

Troubleshooting Decision Tree

Agent screen is blank or not loading
│
├─→ Is there PHP output? (Check via curl test)
│   ├─→ NO: PHP is crashing
│   │   └─→ Check /var/log/apache2/error.log for parse errors
│   │   └─→ Run: php -l /var/www/html/agc/vicidial.php
│   │
│   └─→ YES: HTML is rendering, but JavaScript fails
│       └─→ Press F12, check browser console
│       └─→ Look for CORS errors, WebSocket errors
│       └─→ Check /var/www/html/agc/vicidial*.js files exist
│
├─→ Is database connection working?
│   ├─→ NO: Check MySQL is running, credentials correct
│   │   └─→ Run: php /var/www/html/test_db.php
│   │
│   └─→ YES: Continue to next step
│
├─→ Is the user active in the database?
│   ├─→ NO: Activate user in admin panel
│   │
│   └─→ YES: Continue to next step
│
├─→ Is Apache/PHP responding within timeout?
│   ├─→ NO: Increase max_execution_time in php.ini
│   │   └─→ Check /var/log/apache2/error.log for resource exhaustion
│   │
│   └─→ YES: Likely browser-side issue
│       └─→ Clear cache, try private/incognito window
│       └─→ Try different browser

Common Error Messages and Solutions

Summary

The ViciDial agent screen blank or not loading issue has multiple potential causes spanning PHP configuration, database connectivity, browser compatibility, and Asterisk integration. By systematically working through this tutorial, you will:

1. Identify the root cause using logs, curl testing, and browser developer tools
2. Fix PHP-level issues by addressing syntax errors, timeout settings, and session management
3. Verify database connectivity and user permissions
4. Resolve browser incompatibilities through cache clearing and CORS configuration
5. Optimize performance by tuning Apache workers and MySQL queries
6. Prevent future occurrences with monitoring scripts and documented procedures

Key takeaways:

• Always check /var/log/apache2/error.log first — it catches 80% of PHP issues
• Use php -l and curl to test PHP execution outside the browser
• Verify database and user status before assuming server issues
• Modern browsers require proper HTTPS and CORS headers
• System resource exhaustion (memory, CPU, disk) causes silent failures

Start with Step 1 (error logs), and if that doesn't reveal the issue, move sequentially through the steps. Most blank screen issues resolve at Step 1-3. By documenting your findings and automating health checks, you'll reduce mean-time-to-resolution for future incidents.