Troubleshooting Guide

Quick Diagnosis

Common Symptoms & Solutions

  • Backup won’t start → Check PHP memory and permissions
  • Backup fails mid-process → Increase execution time
  • Plugin won’t activate → Verify PHP version and WordPress compatibility
  • Scheduled backups not working → Check WordPress cron status
  • File access errors → Verify directory permissions

Installation & Activation Issues

Plugin Won’t Activate

Error: “Plugin could not be activated”

Symptoms: Activation fails with generic error message

Causes:

  • PHP version below 7.4
  • Insufficient memory limit
  • File permission issues
  • WordPress version incompatibility

Solutions:

  1. Check PHP Version 
    // Add this to a test file to check PHP version
<?php phpinfo(); ?>
    • Minimum required: PHP 7.4
    • Recommended: PHP 8.0+
  2. Increase Memory Limit
    • Add to wp-config.php:
      • define('WP_MEMORY_LIMIT', '256M');
    • Or contact hosting provider
  3. Check File Permissions
    • Plugin files: 644
    • Plugin directories: 755
    • /wp-content/: 755
  4. Verify WordPress Version
    • Minimum: WordPress 5.0
    • Recommended: WordPress 6.0+

Error: “Directory not writable”

Symptoms: Activation fails due to permission issues

Solutions:

# Set correct permissions
chmod 755 /path/to/wp-content/plugins/
chmod 644 /path/to/wp-content/plugins/vt-db-backup/*.php
chmod 755 /path/to/wp-content/plugins/vt-db-backup/

Plugin Activates But Doesn’t Work

Symptoms: Plugin shows as active but no menu appears

Solutions:

  1. Check User Capabilities
    • Ensure you’re logged in as Administrator
    • Verify user has manage_options capability
  2. Clear Cache
    • Clear WordPress cache
    • Clear browser cache
    • Clear server cache if applicable
  3. Check for Conflicts
    • Deactivate other plugins temporarily
    • Switch to default theme
    • Check error logs

Backup Creation Issues

Backup Won’t Start

Button Unresponsive

Symptoms: Clicking “Create Backup” does nothing

Causes:

  • JavaScript errors
  • AJAX failures
  • Permission issues
  • Memory constraints

Solutions:

  1. Check Browser Console
    • Press F12 → Console tab
    • Look for JavaScript errors
    • Check for AJAX failures
  2. Verify AJAX
    • Check if WordPress AJAX is working
    • Verify nonce values
    • Check user permissions
  3. Memory Issues
    • Increase PHP memory limit
    • Close other browser tabs
    • Restart web server

Backup Fails Immediately

Symptoms: Backup starts but fails within seconds

Causes:

  • Database connection issues
  • Insufficient disk space
  • Permission problems
  • Plugin conflicts

Solutions:

  1. Check Database Connection
    • Verify database credentials
    • Test database connectivity
    • Check database server status
  2. Verify Disk Space 
    # Check available disk space
df -h
# Check directory permissions
ls -la /wp-content/
  3. Review Error Logs
    • Check WordPress debug log
    • Check server error logs
    • Check plugin-specific logs

Backup Stops Mid-Process

Progress Bar Stops

Symptoms: Backup progress stops, no completion

Causes:

  • Execution time limit
  • Memory exhaustion
  • Server timeout
  • Database locks

Solutions:

  1. Increase Execution Time 
    // Add to wp-config.php
set_time_limit(600); // 10 minutes
ini_set('max_execution_time', 600);
  2. Increase Memory Limit 
    // Add to wp-config.php
define('WP_MEMORY_LIMIT', '512M');
define('WP_MAX_MEMORY_LIMIT', '1G');
  3. Check Database Locks 
    -- Check for running processes
SHOW PROCESSLIST;

-- Kill long-running queries if needed
KILL [process_id];

Memory Exhaustion

Symptoms: “Allowed memory size exhausted” error

Solutions:

  1. Immediate Fixes
    • Increase PHP memory limit
    • Enable performance mode
    • Close unnecessary applications
  2. Long-term Solutions
    • Optimize database
    • Use PRO version features
    • Upgrade server resources

Backup File Issues

File Corrupted

Symptoms: Can’t open backup file, restore fails

Causes:

  • Incomplete backup process
  • Disk space issues
  • Compression errors
  • File permission problems

Solutions:

  1. Recreate Backup
    • Delete corrupted file
    • Create new backup
    • Verify file integrity
  2. Check Compression
    • Test with compression disabled
    • Verify Gzip support
    • Check file permissions
  3. Verify File System
    • Check disk integrity
    • Verify write permissions
    • Test disk performance

File Too Large

Symptoms: Backup file size exceeds expectations

Solutions:

  1. Enable Compression
    • Gzip reduces size by 60-80%
    • Check compression settings
    • Verify compression working
  2. Database Optimization
    • Clean up unnecessary data
    • Remove old revisions
    • Optimize tables
  3. Selective Backup (PRO)
    • Choose specific tables
    • Exclude unnecessary data
    • Use incremental backups

Scheduling Issues

Automated Backups Not Working

WordPress Cron Problems

Symptoms: Scheduled backups never run

Causes:

  • WordPress cron disabled
  • Site inactivity
  • Plugin conflicts
  • Server timezone issues

Solutions:

  1. Check Cron Status 
    // Add to functions.php to test cron
add_action('init', function() {
    if (!wp_next_scheduled('vt_db_backup_hourly_backup')) {
        wp_schedule_event(time(), 'hourly', 'vt_db_backup_hourly_backup');
    }
});
  2. Force Cron Execution
    • Visit your site regularly
    • Use external cron jobs
    • Install cron management plugin
  3. Check Timezone
    • Verify WordPress timezone setting
    • Check server timezone
    • Ensure consistency

Settings Not Saved

Symptoms: Schedule settings revert to defaults

Causes:

  • Database write issues
  • Plugin conflicts
  • Permission problems
  • Cache issues

Solutions:

  1. Verify Database Access
    • Check database permissions
    • Test option saving
    • Verify table structure
  2. Clear Cache
    • Clear WordPress cache
    • Clear object cache
    • Clear server cache
  3. Check for Conflicts
    • Deactivate other plugins
    • Switch themes temporarily
    • Check error logs

Performance Issues

Slow Backup Creation

Large Database Handling

Symptoms: Backups take extremely long time

Causes:

  • Very large database
  • Server resource limitations
  • Network issues
  • Database optimization needed

Solutions:

  1. Enable Performance Mode
    • Use –single-transaction
    • Optimize memory usage
    • Enable compression
  2. Server Optimization
    • Increase PHP memory
    • Extend execution time
    • Optimize MySQL settings
  3. Database Optimization
    • Clean up unnecessary data
    • Optimize table structure
    • Remove old revisions

Server Resource Issues

Symptoms: Site becomes slow during backups

Solutions:

  1. Schedule During Low Traffic
    • Choose off-peak hours
    • Monitor server load
    • Coordinate with maintenance
  2. Resource Management
    • Limit concurrent processes
    • Use performance mode
    • Monitor resource usage
  3. Server Upgrades
    • Increase memory
    • Upgrade CPU
    • Optimize storage

Notification Issues

Email Notifications Not Working

No Emails Received

Symptoms: Backup completes but no email notification

Causes:

  • Email configuration issues
  • Server email limitations
  • Plugin settings incorrect
  • Spam filters

Solutions:

  1. Check Email Settings
    • Verify admin email
    • Test WordPress email
    • Check notification settings
  2. Server Email Configuration
    • Verify SMTP settings
    • Check mail server status
    • Test email functionality
  3. Plugin Configuration
    • Enable email notifications
    • Verify email address
    • Test notification system

Slack Notifications (PRO)

Symptoms: Slack webhook not working

Solutions:

  1. Verify Webhook URL
    • Check webhook format
    • Test webhook manually
    • Verify Slack app permissions
  2. Check Plugin Settings
    • Enable Slack notifications
    • Verify webhook URL
    • Test notification system

File Management Issues

Backup Directory Problems

Directory Not Created

Symptoms: Backup directory missing or inaccessible

Causes:

  • Permission issues
  • Disk space problems
  • Plugin activation failure
  • Server configuration

Solutions:

  1. Manual Directory Creation 
    mkdir -p /wp-content/db-backups
chmod 750 /wp-content/db-backups
chown www-data:www-data /wp-content/db-backups
  2. Check Permissions
    • Verify directory permissions
    • Check ownership
    • Test write access
  3. Plugin Reinstallation
    • Deactivate plugin
    • Delete plugin files
    • Reinstall fresh copy

Permission Issues

Symptoms: Can’t write to backup directory

Solutions:

# Set correct permissions
chmod 750 /wp-content/db-backups
chown www-data:www-data /wp-content/db-backups

# Or for shared hosting
chmod 755 /wp-content/db-backups

File Cleanup Issues

Old Backups Not Removed

Symptoms: Backup files accumulate, no automatic cleanup

Causes:

  • Cleanup cron not working
  • Permission issues
  • Plugin conflicts
  • Settings incorrect

Solutions:

  1. Check Cleanup Settings
    • Verify maximum backup count
    • Check cleanup frequency
    • Test manual cleanup
  2. Manual Cleanup
    • Delete old files manually
    • Check file permissions
    • Verify cleanup process
  3. Cron Verification
    • Check WordPress cron status
    • Verify cleanup events
    • Test cron functionality

Advanced Troubleshooting

Debug Mode

Enable WordPress Debug

// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Check Debug Log

  • Location: /wp-content/debug.log
  • Monitor during backup process
  • Look for error messages
  • Check for memory issues

Server Logs

Error Log Locations

  • Apache: /var/log/apache2/error.log
  • Nginx: /var/log/nginx/error.log
  • PHP: /var/log/php/error.log
  • WordPress: /wp-content/debug.log

Log Analysis

  • Look for error patterns
  • Check timestamps
  • Identify resource issues
  • Monitor performance

Database Analysis

Check Database Health

-- Check table status
SHOW TABLE STATUS;

-- Check for errors
CHECK TABLE wp_posts;
REPAIR TABLE wp_posts;

-- Optimize tables
OPTIMIZE TABLE wp_posts;

Performance Queries

-- Check slow queries
SHOW VARIABLES LIKE 'slow_query_log';

-- Check query cache
SHOW VARIABLES LIKE 'query_cache%';

Getting Help

Before Contacting Support

Information to Gather

  • Error Messages: Exact error text
  • System Details: PHP, MySQL, WordPress versions
  • Plugin Version: Current plugin version
  • Server Environment: Hosting provider, server type
  • Steps to Reproduce: Detailed reproduction steps

Basic Troubleshooting

  1. Test with default settings
  2. Deactivate other plugins
  3. Switch to default theme
  4. Check server requirements
  5. Review error logs

Support Resources

Free Support

  • WordPress.org Forums: Community support
  • Documentation: This troubleshooting guide
  • GitHub Issues: Bug reports and feature requests

PRO Support

  • Priority Support: Direct developer access
  • Email Support: support@visiontech.consulting
  • Live Chat: Available for PRO users
  • Custom Solutions: Tailored assistance

Contact Information

Support Channels

  • Email: support@visiontech.consulting
  • Website: https://visiontech.consulting/support
  • Documentation: https://visiontech.consulting/vt-db-backup/docs
  • PRO Support: Priority assistance for paid users

Still having issues? Contact our support team or upgrade to PRO for priority assistance.