Troubleshooting Guide ​

This comprehensive troubleshooting guide helps you resolve common issues with WP Rollback and provides solutions for both basic and advanced problems.

Common Issues and Solutions ​

Installation and Activation Issues ​

Plugin Won't Activate ​

Symptoms: Error message when trying to activate WP Rollback

Possible Causes:

• PHP version incompatibility
• Missing required PHP extensions
• File permission issues
• Plugin conflicts

Solutions:

1. Check PHP Version: Ensure PHP 7.4 or higher (see System Requirements)
2. Verify Extensions: Check required PHP extensions are installed (see System Requirements)
3. File Permissions: Ensure plugin directory has correct permissions (755)
4. Plugin Conflicts: Deactivate other plugins and test

License Activation Problems (Pro) ​

Symptoms: Pro license won't activate or validates incorrectly

Possible Causes:

• Incorrect license key
• License exceeds site limit
• Server connectivity issues
• Licensing server downtime

Solutions:

1. Verify License Key: Double-check license key spelling and format
2. Check License Status: Verify license is active and not expired
3. Deactivate Other Sites: Deactivate license on other sites if limit reached
4. Check Connectivity: Ensure server can connect to licensing server

Rollback Process Issues ​

"Version Not Available" Error ​

Symptoms: Selected version shows as not available for rollback

Possible Causes:

• Plugin/theme not from WordPress.org repository
• Very old version removed from repository
• Premium plugin/theme archives exist but no UI access (free version)

Solutions:

1. Check Repository: Verify plugin/theme is available on WordPress.org
2. Try Different Version: Select a more recent version
3. Check Archives: Look in wp-content/uploads/wp-rollback/ for premium archives
4. Pro License: Activate Pro license for UI access to premium rollbacks
5. Contact Support: If issue persists, contact support

Rollback Process Hangs or Fails ​

Symptoms: Rollback starts but never completes or fails partway through

Possible Causes:

• Insufficient file permissions
• Disk space limitations
• Memory or timeout limitations
• File corruption issues

Solutions:

1. Check Permissions: Verify write permissions on plugin/theme directories
2. Free Disk Space: Ensure sufficient free disk space
3. Increase Limits: Increase PHP memory_limit and max_execution_time
4. Manual Verification: Check for file corruption or incomplete downloads

Permission Denied Errors ​

Symptoms: "Permission denied" errors during rollback process

Possible Causes:

• Incorrect file permissions
• Ownership issues
• Hosting provider restrictions

Solutions:

1. File Permissions: Set correct permissions (755 for directories, 644 for files)
2. Ownership: Ensure web server owns the files
3. Hosting Support: Contact hosting provider for permission issues

Premium Assets Not Showing Rollback Options ​

Symptoms: No rollback options available for premium plugins or themes

Possible Causes:

• No updates performed since WP Rollback installation (free or pro)
• Using free version (archives created but no UI)
• Pro license not properly activated
• Plugin/theme doesn't update through WordPress

Solutions:

1. Check Archives: Look in wp-content/uploads/wp-rollback/ to see if archives exist or use Pro UI to view archives page.
2. Perform an Update: If no archives exist, WP Rollback must be installed BEFORE updates occur
3. Activate Pro: If archives exist, activate Pro for UI access
4. Verify WordPress Updates: Ensure the plugin/theme updates through WordPress's built-in system

Important: WP Rollback (free or pro) can only function as an "escape hatch" if it was installed BEFORE the problematic update occurred. It must be present during updates to capture archives. If you're experiencing issues from a recent update and didn't have WP Rollback installed beforehand, you'll need to restore from a backup.

Backup Creation Issues ​

Automatic Backups Not Being Created ​

Symptoms: No backup archives found in wp-content/uploads/wp-rollback/ after plugin/theme updates

Possible Causes:

• WP Rollback not installed when update occurred
• Insufficient disk space
• Write permission issues on uploads directory
• Missing PHP extensions (will use fallback)

Solutions:

1. Install Before Updating: WP Rollback must be active BEFORE you update plugins/themes
2. Check Disk Space: Ensure adequate free disk space (see System Requirements)
3. Verify Permissions: Ensure wp-content/uploads is writable
4. Check PHP Extensions: While not required, the PHP ZipArchive extension improves performance (see System Requirements)

"Failed to Create Backup" Error During Updates ​

Symptoms: Error message appears when other plugins/themes are updated

Possible Causes:

• Insufficient disk space
• Permission issues
• Memory limitations
• Corrupted filesystem

Solutions:

1. Free Disk Space: Delete old backups or unused files
2. Check Error Logs: Look in wp-content/debug.log for specific errors
3. Increase Memory: Raise PHP memory_limit (see System Requirements)
4. Repair Filesystem: Check and repair filesystem if on VPS/dedicated server

Slow Backup Creation ​

Symptoms: Updates take significantly longer than usual

Possible Causes:

• Using PclZip fallback instead of ZipArchive
• Large plugin/theme files
• Slow disk I/O

Solutions:

1. Enable ZipArchive: Install the PHP ZipArchive extension for 3-5x faster backups (see System Requirements)
2. Optimize Server: Upgrade to faster storage (SSD vs HDD)
3. Review Archive Limits: In Pro settings, adjust the archive limit to reduce disk usage

Version and Compatibility Issues ​

Plugin/Theme Won't Activate After Rollback ​

Symptoms: Plugin or theme won't activate after successful rollback

Possible Causes:

• Version incompatibility with current WordPress version
• Missing dependencies
• Database schema conflicts
• PHP version incompatibility

Solutions:

1. WordPress Compatibility: Check plugin/theme WordPress version requirements
2. Dependency Check: Verify all required plugins/themes are present
3. Database Updates: Run any required database updates
4. PHP Compatibility: Ensure PHP version meets requirements

Settings or Data Lost After Rollback ​

Symptoms: Plugin/theme settings disappear after rollback

Possible Causes:

• Settings format changed between versions
• Database table structure changes
• Option names changed
• Data migration issues

Solutions:

1. Settings Restore: Restore settings from previous configuration if available
2. Database Check: Verify database tables and options are intact
3. Version Comparison: Check differences between versions
4. Manual Reconfiguration: Reconfigure settings manually if necessary

Performance Issues ​

Slow Rollback Process ​

Symptoms: Rollbacks take much longer than expected

Possible Causes:

• Large plugin/theme files
• Slow internet connection
• Server resource limitations
• Multiple simultaneous operations

Solutions:

1. Connection Speed: Test and improve internet connection
2. Resource Allocation: Increase server resources (CPU, memory)
3. Optimize Settings: Adjust WP Rollback performance settings
4. Schedule Operations: Perform rollbacks during low-traffic times

Site Performance Degradation ​

Symptoms: Site becomes slower after installing WP Rollback

Possible Causes:

• Plugin overhead
• Inefficient caching
• Resource conflicts
• Database queries

Solutions:

1. Performance Monitoring: Monitor site performance metrics
2. Cache Optimization: Optimize caching settings
3. Query Optimization: Identify and optimize slow database queries
4. Resource Monitoring: Monitor server resource usage

Network and Connectivity Issues ​

Download Failures ​

Symptoms: Plugin/theme downloads fail during rollback

Possible Causes:

• Network connectivity issues
• Firewall restrictions
• SSL certificate problems
• WordPress.org API issues

Solutions:

1. Network Test: Test connectivity to WordPress.org
2. Firewall Check: Verify firewall allows outbound connections
3. SSL Verification: Check SSL certificate validity
4. Alternative Methods: Use manual download as fallback

API Connection Problems ​

Symptoms: Cannot connect to WordPress.org API

Possible Causes:

• Blocked ports or protocols
• Proxy server issues
• DNS resolution problems
• Server-side restrictions

Solutions:

1. Port Check: Verify required ports are open
2. Proxy Configuration: Configure proxy settings if needed
3. DNS Test: Test DNS resolution for target domains
4. Server Configuration: Check server-side restrictions

Database and File System Issues ​

Database Connection Errors ​

Symptoms: Database errors during rollback process

Possible Causes:

• Database server downtime
• Connection limit exceeded
• Corrupt database tables
• Insufficient database permissions

Solutions:

1. Database Status: Check database server status
2. Connection Limits: Increase database connection limits
3. Table Repair: Repair corrupt database tables
4. Permission Check: Verify database user permissions

File System Errors ​

Symptoms: File system errors during rollback operations

Possible Causes:

• Permission restrictions
• Disk space exhaustion
• File system corruption

Solutions:

1. Permission Audit: Audit and correct file permissions
2. Disk Space: Free up disk space
3. File System Check: Run file system check and repair

Advanced Troubleshooting ​

Debug Mode and Logging ​

Enabling Debug Mode ​

Add these constants to your wp-config.php file:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

WP Rollback Debug Options ​

Enable specific WP Rollback debugging:

1. Navigate to Tools > WP Rollback > Settings
2. Enable Debug Mode
3. Set Log Level to appropriate level
4. Check logs in /wp-content/debug.log

Log Analysis ​

• Error Patterns: Look for recurring error patterns
• Timing Issues: Check for timeout or timing-related errors
• Memory Usage: Monitor memory usage during operations
• API Responses: Check API response codes and messages

Manual Rollback Procedures ​

Manual Plugin Rollback ​

If automatic rollback fails:

1. Download Version: Download desired version from WordPress.org
2. Deactivate Plugin: Deactivate the plugin in WordPress admin
3. Preserve Current: Preserve current plugin directory
4. Replace Files: Replace plugin files with downloaded version
5. Reactivate Plugin: Reactivate the plugin

Manual Theme Rollback ​

If automatic theme rollback fails:

1. Download Theme: Download desired theme version
2. Preserve Current: Preserve current theme directory
3. Replace Files: Replace theme files with downloaded version
4. Clear Cache: Clear any theme caches
5. Verify Operation: Check site frontend and admin

Database Troubleshooting ​

Database Query Analysis ​

Monitor database queries during rollbacks:

1. Query Logging: Enable MySQL query logging
2. Performance Analysis: Analyze slow query log
3. Index Optimization: Optimize database indexes
4. Query Caching: Implement query caching

Database Repair and Maintenance ​

• Table Repair: Use MySQL REPAIR TABLE command
• Database Optimization: Run database optimization routines
• Database Verification: Verify database integrity is complete
• Consistency Checks: Run database consistency checks

Server Configuration Issues ​

PHP Configuration ​

Check and adjust PHP settings:

memory_limit = 256M
max_execution_time = 300
upload_max_filesize = 64M
post_max_size = 64M

Web Server Configuration ​

• Apache: Check .htaccess files for conflicts
• Nginx: Verify Nginx configuration
• IIS: Check IIS settings and modules
• Resource Limits: Ensure adequate resource limits

Hosting Environment ​

• Shared Hosting: Check shared hosting limitations
• VPS/Dedicated: Verify server configuration
• Cloud Hosting: Check cloud-specific settings
• Managed WordPress: Verify managed hosting compatibility

Specific Error Messages ​

"Fatal Error: Class Not Found" ​

Cause: Missing or corrupted plugin files Solution: Reinstall plugin or restore from previous installation

"HTTP Error 500" ​

Cause: PHP fatal error during rollback Solution: Check error logs, increase memory limit, debug PHP issues

"HTTP Error 404" ​

Cause: Plugin/theme files not found Solution: Verify file paths, check file permissions, restore missing files

"Database Error" ​

Cause: Database connection or query issues Solution: Check database connectivity, repair tables, verify permissions

"Timeout Error" ​

Cause: Operation exceeded time limit Solution: Increase max_execution_time, optimize process, break into smaller operations

"Permission Error" ​

Cause: Insufficient file system permissions Solution: Check and correct file permissions, verify ownership

Prevention and Best Practices ​

Regular Maintenance ​

• Regular Maintenance: Maintain regular site maintenance
• Update Monitoring: Monitor plugin/theme updates
• Performance Monitoring: Regular performance checks
• Security Scanning: Regular security scans

Environment Preparation ​

• Staging Environment: Always test rollbacks on staging
• Resource Allocation: Ensure adequate server resources
• Safety Strategy: Implement comprehensive safety strategy
• Documentation: Document rollback procedures

Monitoring and Alerting ​

• Error Monitoring: Set up error monitoring and alerts
• Performance Alerts: Configure performance alerts
• Uptime Monitoring: Monitor site uptime
• Log Analysis: Regular log analysis and review

When to Contact Support ​

Free Plugin Support ​

• WordPress.org Forums: Post in plugin support forums
• Bug Reports: Report bugs through support channels
• Documentation: Check documentation for solutions
• Community Support: Engage with community for help

Pro Plugin Support ​

• Priority Support: Access priority support channels
• Direct Contact: Contact support directly
• Phone Support: Use phone support for urgent issues
• Custom Solutions: Request custom solutions if needed

Information to Provide ​

When contacting support, provide:

• WordPress Version: Current WordPress version
• PHP Version: Current PHP version
• Plugin Version: WP Rollback version
• Error Messages: Complete error messages
• Debug Logs: Relevant debug log entries
• Steps to Reproduce: Detailed steps to reproduce the issue

Next Steps ​

• Review FAQ for frequently asked questions
• Explore Developer Guide for custom solutions