Troubleshooting

Comprehensive troubleshooting guide for Virtual Files plugin. Find solutions to common issues and optimize performance.

Installation Issues

Plugin Won't Activate

Symptoms:

• White screen after activation
• Fatal error messages
• Plugin not appearing in admin

Solutions:

1. Check PHP Version

   • WordPress requires PHP 7.4+ (8.0+ recommended)
   • Check with your hosting provider
   • Update if necessary

2. Increase Memory Limit

   • Increase WordPress memory limit to 256M+
   • Contact hosting provider if needed

3. Check for Conflicts

   • Temporarily disable other plugins
   • Activate default WordPress theme
   • Check for plugin-specific conflicts

4. Enable Debug Mode

   • Add define('WP_DEBUG', true); to wp-config.php
   • Check error logs for details

5. Verify Database Connection

   • Ensure WordPress can connect to database
   • Check database credentials in wp-config.php

File Access Issues

Virtual Files Return 404

Symptoms:

• Virtual file URLs show 404 errors
• "File not found" messages
• WordPress 404 template displayed

Solutions:

1. Flush Rewrite Rules

   • Go to Virtual Files → Settings
   • Click Flush Rewrite Rules
   • Or visit Settings → Permalinks and click Save Changes

2. Check File Status

   • Edit virtual file in WordPress admin
   • Ensure status is set to "Active"
   • Save changes

3. Verify Server Configuration

   • Ensure .htaccess is writable
   • Verify server supports rewrite rules
   • Contact hosting provider if needed

4. Clear Caching

   • Clear all server caches
   • Clear WordPress cache
   • Clear browser cache

Incorrect MIME Types

Symptoms:

• Files download instead of displaying
• Browser shows raw text instead of formatted content
• Content-Type headers incorrect

Solutions:

1. Check File Extension

   • Ensure correct file extension (.txt, .json, .xml, etc.)
   • Verify extension matches file content

2. Test Headers

   • Use browser developer tools to check Content-Type headers
   • Verify headers match file type

3. Clear Caches

   • Clear browser cache
   • Clear server cache
   • Test with different browser

Performance Issues

Slow File Loading

Symptoms:

• Virtual files load slowly
• High server response times
• Timeouts on large files

Solutions:

1. Enable Caching (Pro version)

   • Go to Virtual Files → Settings
   • Enable Performance Caching
   • Set appropriate TTL (1-24 hours)

2. Clear Caches

   • Clear Virtual Files cache (Pro version)
   • Clear server cache
   • Clear browser cache

3. Optimize Database

   • Optimize WordPress database
   • Clean up post revisions
   • Use proper database indexing

4. Check Server Resources

   • Verify adequate server memory
   • Check CPU usage
   • Monitor disk space

Admin Interface Issues

Admin Pages Not Loading

Symptoms:

• Blank admin pages
• JavaScript errors in console
• CSS not loading properly

Solutions:

1. Check Browser Console

   • Open browser developer tools
   • Look for JavaScript errors
   • Clear browser cache

2. Plugin Conflicts

   • Temporarily disable other plugins
   • Test with default WordPress theme
   • Re-enable plugins one by one

3. Memory Issues

   • Increase WordPress memory limit
   • Check server error logs
   • Contact hosting provider

Settings Not Saving

Symptoms:

• Settings reset to defaults
• "Settings not saved" message
• AJAX errors in console

Solutions:

1. Check AJAX Handler

   • Verify AJAX endpoints are working
   • Check for JavaScript errors

2. Check Nonce Verification

   • WordPress security tokens may be failing
   • Try refreshing the page

3. Check Database Permissions

   • Ensure WordPress can write to options table
   • Verify database user has correct permissions

4. Clear Caches

   • Clear all caches
   • Try saving again

Security Issues

Access Control Problems

Symptoms:

• Unauthorized users can access files
• Permission checks failing
• Security warnings

Solutions:

1. Verify User Roles

   • Check user capabilities in WordPress admin
   • Ensure proper role assignments

2. Check Plugin Permissions

   • Verify WordPress file permissions
   • Check server security settings

3. Update Plugin

   • Ensure latest Virtual Files version
   • Check for security updates

Content Security Issues

Symptoms:

• Security warnings in browser
• Content not displaying correctly
• Potential XSS vulnerabilities

Solutions:

1. Validate Content

   • Ensure file content is properly formatted
   • Check for malicious code

2. Check Output Headers

   • Verify Content-Type headers are correct
   • Ensure security headers are present

3. Update WordPress

   • Keep WordPress core updated
   • Update all plugins

Debugging Tools

Enable Debug Mode

Add to wp-config.php:

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

Check Debug Logs

• WordPress debug log: wp-content/debug.log
• Server error logs: Check with hosting provider
• PHP error logs: Check with hosting provider

Test Virtual Files

1. Direct URL Test

   • Access virtual file URL directly in browser
   • Check HTTP response headers
   • Verify content displays correctly

2. Header Test

   curl -I https://yourdomain.com/your-file.txt

3. Error Log Check

   • Check WordPress debug log for errors
   • Check server error logs
   • Check PHP error logs

Getting Help

Self-Service Resources

1. Documentation: Browse our complete documentation
2. FAQ: Check frequently asked questions
3. Community Forums: Search WordPress.org forums

Contact Support

Free Version:

• WordPress.org Forums: Community support
• Documentation: Self-service resources
• Bug Reports: Report issues on WordPress.org

Pro Version:

• Priority Email: Available through WordPress admin or Freemius
• Direct Support: Developer assistance available

Reporting Issues

When reporting issues, please include:

1. Environment Information:

   • WordPress version
   • PHP version
   • Server software (Apache/Nginx)
   • Browser and version
   • Other active plugins

2. Error Details:

   • Exact error message
   • Steps to reproduce
   • Expected vs actual behavior
   • Frequency of occurrence

3. Debug Information:

   • WordPress debug log entries
   • Browser console errors
   • Server error logs
   • Screenshots if applicable

Prevention Tips

Regular Maintenance

1. Monitor Performance

   • Check file access times regularly
   • Monitor server resource usage
   • Set up performance alerts

2. Keep Updated

   • Update Virtual Files regularly
   • Update WordPress core
   • Update PHP and server software
   • Monitor security advisories

3. Backup Regularly

   • Backup WordPress database
   • Backup virtual files settings
   • Backup plugin files
   • Test restore procedures

4. Security Audits

   • Review file access logs
   • Scan for vulnerabilities
   • Review user permissions
   • Test security measures

By following this troubleshooting guide, you should be able to resolve most common issues with Virtual Files plugin. If problems persist, don't hesitate to contact our support team.