DEV Community

Moisi Trungu
Moisi Trungu

Posted on • Originally published at flixzone.icu

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

#devops #linux #sip #voip

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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...
Enter fullscreen mode Exit fullscreen mode

Then reload the agent screen and check the debug log:

tail -50 /var/log/php-debug.log
Enter fullscreen mode Exit fullscreen mode

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());
}
?>
Enter fullscreen mode Exit fullscreen mode

Access this from your browser:

http://YOUR_VICIDIAL_IP/test_db.php
Enter fullscreen mode Exit fullscreen mode

Or from command line:

php /var/www/html/test_db.php
Enter fullscreen mode Exit fullscreen mode

Check Database Permissions

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

mysql -u root -p
Enter fullscreen mode Exit fullscreen mode 
-- 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;
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

Step 3: Check PHP Configuration and Resource Limits

Verify PHP Settings

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

<?php phpinfo(); ?>
Enter fullscreen mode Exit fullscreen mode

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\";"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Restart PHP-FPM or Apache 

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

# If using mod_php with Apache
systemctl restart apache2
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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/*
Enter fullscreen mode Exit fullscreen mode

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...
?>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Review vicidial.conf Settings 

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

Check for database connection parameters:

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

Example output:

db_host=localhost
db_name=asterisk
db_user=cron
db_pass=1234
Enter fullscreen mode Exit fullscreen mode

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';"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode

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)"
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Restart:

systemctl restart apache2
Enter fullscreen mode Exit fullscreen mode

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;"
Enter fullscreen mode Exit fullscreen mode

Then have the agent login and check:

tail -50 /var/log/mysql/slow.log | grep vicidial
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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;"
Enter fullscreen mode Exit fullscreen mode

Restart ViciDial Services 

# Restart Asterisk
systemctl restart asterisk

# Restart Apache
systemctl restart apache2

# Restart MySQL (if changes were made)
systemctl restart mysql
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 ---"
Enter fullscreen mode Exit fullscreen mode

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 -
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Restart rsyslog:

systemctl restart rsyslog
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Common Error Messages and Solutions

Error Location Solution
"SQLSTATE[HY000]: General error: 1030" PHP error log MySQL temp table issue, restart MySQL
"PHP Fatal error: Allowed memory size exhausted" Apache error log Increase memory_limit in php.ini
"Warning: session_start(): open_basedir restriction in effect" Apache error log Fix /var/lib/php/sessions permissions
"CORS policy: Cross-origin request blocked" Browser console Add CORS headers to Apache vhost
"Failed to connect to localhost:5900" Browser console Non-critical, asterisk connection issue
"Cannot read properties of undefined" Browser console JavaScript didn't load, check /agc/ directory
"Connection timeout" Network tab in F12 Firewall or network latency issue

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.

Top comments (0)