Troubleshooting

This comprehensive troubleshooting guide covers common issues, their causes, and step-by-step solutions for Plain Classes Gutenberg. Follow the diagnostic steps to quickly identify and resolve problems.

🚨 Quick Diagnostic Checklist

Before diving into specific issues, run through this quick checklist:

✅ Basic Requirements

  • [ ] WordPress 5.0+ installed
  • [ ] PHP 7.4+ running
  • [ ] Plugin activated successfully
  • [ ] Valid license key activated
  • [ ] User has administrator privileges
  • [ ] JavaScript enabled in browser

✅ Plugin Status

  • [ ] Plugin appears in admin menu under Tools
  • [ ] No PHP errors in debug log
  • [ ] Database tables created successfully
  • [ ] Asset files loaded correctly

🔧 Installation & Licensing Issues

Plugin Won’t Activate

Symptoms:

  • Fatal error during activation
  • Plugin deactivates immediately
  • White screen on activation

Common Causes & Solutions:

Memory Limit Exceeded

Fatal error: Allowed memory size exhausted

Solution:

// In wp-config.php
ini_set('memory_limit', '512M');
// Or contact hosting provider

Plugin Conflicts

Cannot redeclare function/class

Solution:

  1. Deactivate all other plugins
  2. Activate Plain Classes Gutenberg
  3. Reactivate plugins one by one to identify conflict
  4. Contact support with conflicting plugin details

PHP Version Too Old

Parse error: syntax error, unexpected ':'

Solution:

  • Upgrade to PHP 7.4+ (8.0+ recommended)
  • Contact hosting provider for PHP upgrade

License Activation Problems

Invalid License Key

Symptoms: “Invalid license key” error
Solutions:

  1. Copy Key Carefully:

    • Copy entire key from purchase email
    • Check for extra spaces or characters
    • Paste into license field without formatting

  2. Verify Purchase:

    • Check DPlugins account for valid purchase
    • Ensure license hasn’t expired
    • Confirm correct product license

Site Limit Exceeded

Symptoms: “Site limit reached” error
Solutions:

  1. Check Active Sites:

    • Log into DPlugins account
    • View active site licenses
    • Deactivate unused sites

  2. Upgrade License:

    • Purchase additional site licenses
    • Upgrade to higher tier plan

Connection Issues

Symptoms: “Could not connect to license server”
Solutions:


  1. Check Internet Connection:


    # Test connectivity from server
    curl -I https://dplugins.com/

  2. Firewall/Security:

    • Whitelist dplugins.com in firewall
    • Check hosting provider security settings
    • Verify outbound HTTPS allowed

🎨 Frontend Assistant Issues

Assistant Won’t Appear

Not Triggering on Click

Symptoms: Cmd/Ctrl+Click does nothing
Debug Steps:

  1. Check License Status:

    • Go to Tools → Plain Classes Gutenberg → License
    • Verify green “Active” status

  2. Verify Settings:

    • Go to Settings tab
    • Ensure “Enable Frontend Assistant” is checked
    • Save settings

  3. Check User Permissions:


    // Must be logged in as administrator
    if (!current_user_can('administrator')) {
       // Assistant won't load
    }

  4. Browser Console Check:

    • Open browser developer tools (F12)
    • Look for JavaScript errors
    • Check for “PCGUTEN” object in console

Common Console Errors:

// Missing dependencies
Uncaught ReferenceError: PCGUTEN is not defined

// Solution: Check script loading order

Assistant Appears but Not Functional

Symptoms: Popup shows but buttons don’t work
Solutions:

  1. Clear Browser Cache:

    • Hard refresh (Ctrl+F5)
    • Clear all browser data
    • Try incognito/private mode

  2. Check CSS Conflicts:


    /* Theme may override assistant styles */
    .pcguten-assistant {
       z-index: 99999 !important;
    }

  3. JavaScript Conflicts:

    • Disable other plugins temporarily
    • Check for jQuery version conflicts
    • Test with default WordPress theme

Element Selection Issues

Can’t Select Certain Elements

Symptoms: Click doesn’t highlight element
Solutions:


  1. CSS Pointer Events:


    /* Element may have pointer-events disabled */
    .problematic-element {
       pointer-events: auto !important;
    }

  2. Try Child Elements:

    • Click on child elements instead
    • Use navigation buttons to reach element
    • Check element structure in browser inspector

  3. Z-index Issues:


    /* Overlay may be blocking clicks */
    .overlay-element {
       z-index: 1;
    }

Classes Don’t Apply

Symptoms: Classes added but no visual change
Debug Process:


  1. Check CSS Specificity:


    /* Theme styles may override */
    .theme-class {
       color: red !important;
    }

    /* Solution: Use higher specificity */
    .my-class.my-class {
       color: blue !important;
    }

  2. Verify CSS Framework:

    • Ensure TailwindCSS/Bootstrap is loaded
    • Check framework version compatibility
    • Test with known working classes

  3. Browser Inspector:

    • Open browser dev tools
    • Check if classes are actually added to element
    • Look for CSS conflicts

📝 Block Autocomplete Issues

No Suggestions Appearing

Autocomplete Panel Missing

Symptoms: “Plain Classes” panel not in block editor
Solutions:

  1. Plugin Active Check:

    • Verify plugin is activated
    • Check license is valid
    • Refresh block editor page

  2. Clear Editor Cache:


    // In browser console
    localStorage.clear();
    sessionStorage.clear();
    location.reload();

  3. Block Editor Compatibility:

    • Test with core WordPress blocks
    • Check for Gutenberg plugin conflicts
    • Try disabling other block editor plugins

Panel Present but No Suggestions

Symptoms: Text area works but no autocomplete dropdown
Debug Steps:

  1. Check Class Database:

    • Go to Class Manager
    • Verify classes exist
    • Import test classes if empty

  2. Console Debugging:


    // Check autocomplete data
    console.log(window.plain_classes);

    // Should show:
    // {winden_classes: "...", ...}


  3. Clear Cache:


    wp-admin/admin.php?page=plain-classes-gutenberg&pcguten_clear_cache=1

Performance Issues

Slow Autocomplete Response

Symptoms: Long delay before suggestions appear
Solutions:

  1. Reduce Class Library Size:

    • Export classes as backup
    • Remove unused classes
    • Optimize class categorization

  2. Clear Transient Cache:


    // Add to functions.php temporarily
    delete_transient('pcguten_merged_classes');

  3. Check Server Performance:

    • Monitor PHP memory usage
    • Check database query performance
    • Consider upgrading hosting plan

🔍 File Scanning Issues

Manual Scanning Problems

No Files Found in Browser

Symptoms: File tree is empty or incomplete
Solutions:


  1. File Permissions:


    # Ensure web server can read files
    chmod 755 /wp-content/themes/
    chmod 644 /wp-content/themes/*/style.css

  2. Path Resolution:

    • Check file paths are correct
    • Verify files actually exist
    • Test with simple paths first

  3. Security Restrictions:


    // May need to adjust allowed paths
    add_filter('pcguten_allowed_scan_paths', function($paths) {
       $paths[] = '/custom/path/';
       return $paths;
    });

Scan Finds No Classes

Symptoms: Scan completes but 0 classes found
Debug Process:

  1. File Content Check:

    • Manually verify files contain CSS classes
    • Check file encoding (should be UTF-8)
    • Look for syntax errors in CSS

  2. Pattern Matching:


    /* Valid patterns */
    .my-class { color: red; }
    <div class="container">

    /* Invalid patterns */
    // Some formats may not be detected


  3. Debug Scanning:


    // Enable debug logging
    add_filter('pcguten_debug_scanning', '__return_true');
    // Check debug.log for scan details

Automatic Scanning Issues

Auto-scan Not Triggering

Symptoms: No scan after saving post
Debug Steps:


  1. Verify Post Type:


    // Check configured post types
    $types = apply_filters('pcguten_auto_scan_post_types', ['scorg']);
    // Default is only 'scorg'

  2. Check Save Method:

    • Auto-scan works with “Update” button
    • Also works with Ctrl+S/Cmd+S shortcuts
    • Verify post actually saves successfully

  3. WordPress Cron:


    // Check if WP Cron is working
    wp_get_scheduled_event('pcguten_async_css_scan');

    // Test cron manually
    wp_cron();


  4. Disable Auto-scan Temporarily:


    // In functions.php for testing
    add_filter('pcguten_enable_auto_scan', '__return_false');

Scanning Causes Performance Issues

Symptoms: Site slowdown after enabling auto-scan
Solutions:

  1. Reduce Scan Scope:

    • Select fewer files/folders
    • Exclude large directories
    • Avoid binary files

  2. Optimize Scan Timing:


    // Increase delay before scan
    add_filter('pcguten_scan_delay', function() {
       return 10; // 10 seconds instead of 3
    });


  3. Memory Management:


    // Increase memory limit
    add_filter('pcguten_scan_memory_limit', function() {
       return '512M';
    });

📊 Database & Performance Issues

Database Connection Problems

Tables Not Created

Symptoms: Plugin active but features don’t work
Solutions:


  1. Manual Table Creation:


    -- Run in phpMyAdmin or similar
    CREATE TABLE wp_pcguten_classes (
       id int(11) NOT NULL AUTO_INCREMENT,
       name varchar(255) NOT NULL,
       type enum('imported','scanned','gutenberg') NOT NULL,
       created_at datetime DEFAULT CURRENT_TIMESTAMP,
       PRIMARY KEY (id),
       UNIQUE KEY name_type (name, type)
    );

  2. Check Database Permissions:

    • Verify WordPress user can CREATE tables
    • Check database connection in wp-config.php
    • Test with other plugins that create tables

Classes Not Saving

Symptoms: Import appears successful but classes disappear
Debug Process:


  1. Check Database Errors:


    // Enable WordPress debug logging
    define('WP_DEBUG_LOG', true);
    // Check /wp-content/debug.log


  2. Test Database Operations:


    // Test basic database function
    global $wpdb;
    $result = $wpdb->get_results("SHOW TABLES LIKE '{$wpdb->prefix}pcguten_classes'");
    var_dump($result);


  3. Character Set Issues:


    -- Check table character set
    SHOW CREATE TABLE wp_pcguten_classes;

    -- Should be utf8mb4_unicode_ci

Memory & Performance Issues

Out of Memory Errors

Symptoms:

Fatal error: Allowed memory size of X bytes exhausted

Solutions:


  1. Increase PHP Memory:


    // wp-config.php
    ini_set('memory_limit', '512M');
    define('WP_MEMORY_LIMIT', '512M');

  2. Optimize Operations:

    • Process classes in smaller batches
    • Clear unnecessary transients
    • Reduce autocomplete class limit

  3. Profile Memory Usage:


    // Add to plugin for debugging
    error_log('Memory usage: ' . memory_get_usage(true));

Slow Page Loading

Symptoms: Admin pages load slowly
Diagnostic Steps:


  1. Check Class Count:


    SELECT type, COUNT(*) FROM wp_pcguten_classes GROUP BY type;


  2. Clear All Caches:


    ?pcguten_clear_cache=1


  3. Database Optimization:


    -- Ensure proper indexes exist
    SHOW INDEX FROM wp_pcguten_classes;

🔄 Import/Export Issues

JSON Import Problems

Invalid JSON Format

Symptoms: “Invalid JSON” error on import
Solutions:

  1. Validate JSON:

    • Use JSONLint
    • Check for trailing commas
    • Verify quote marks are correct

  2. File Encoding:

    • Save file as UTF-8
    • Avoid BOM (Byte Order Mark)
    • Use plain text editor

  3. File Size Limits:


    // Check upload limits
    echo ini_get('upload_max_filesize');
    echo ini_get('post_max_size');

Classes Import but Don’t Appear

Symptoms: Successful import message but no classes visible
Debug Process:


  1. Check Database:


    SELECT COUNT(*) FROM wp_pcguten_classes WHERE type = 'imported';

  2. Clear Frontend Cache:

    • Browser cache
    • Plugin cache
    • CDN cache if applicable

  3. Verify Import Type:

    • Check if classes imported as correct type
    • Verify merge settings were correct

🌐 Browser & Compatibility Issues

Browser-Specific Problems

Chrome Issues

Common Problems:

  • Security policies blocking scripts
  • Extension conflicts
  • CORS restrictions

Solutions:

// Check for Chrome-specific errors
if (navigator.userAgent.includes('Chrome')) {
    // Chrome-specific debugging
}

Safari Issues

Common Problems:

  • Webkit rendering differences
  • Touch event handling
  • Local storage restrictions

Mobile Browser Issues

Common Problems:

  • Touch + Hold not working
  • Assistant positioning problems
  • Viewport scaling issues

Solutions:

/* Mobile-specific fixes */
@media (max-width: 768px) {
    .pcguten-assistant {
        position: fixed !important;
        width: 90% !important;
    }
}

JavaScript Framework Conflicts

jQuery Conflicts

Symptoms: “$ is not defined” errors
Solution:

// Use WordPress jQuery safely
jQuery(document).ready(function($) {
    // Plugin code here
});

React/Vue Conflicts

Symptoms: Frontend frameworks interfere with assistant
Solutions:


  1. Scope Isolation:


    // Ensure plugin code is properly scoped
    if (typeof PCGUTEN !== 'undefined') {
       // Safe to use plugin
    }


  2. Event Delegation:


    // Use event delegation for dynamic content
    document.addEventListener('click', function(e) {
       if (e.ctrlKey || e.metaKey) {
           // Handle click
       }
    });

🛠️ Advanced Troubleshooting

Debug Mode Setup

Enable Full Debug Logging

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

// Plugin-specific debugging
define('PCGUTEN_DEBUG', true);

Debug Information Collection

// Add to functions.php for diagnostic info
function pcg_debug_info() {
    global $wpdb;

    echo "<h3>Plugin Debug Info</h3>";
    echo "WordPress Version: " . get_bloginfo('version') . "<br>";
    echo "PHP Version: " . phpversion() . "<br>";
    echo "Memory Limit: " . ini_get('memory_limit') . "<br>";

    // Check tables
    $tables = $wpdb->get_results("SHOW TABLES LIKE '{$wpdb->prefix}pcguten_%'");
    echo "Plugin Tables: " . count($tables) . "<br>";

    // Check classes
    $class_count = $wpdb->get_var("SELECT COUNT(*) FROM {$wpdb->prefix}pcguten_classes");
    echo "Total Classes: " . $class_count . "<br>";

    // Check license
    $license_status = get_option('PCGUTEN_license_status');
    echo "License Status: " . $license_status . "<br>";
}
add_action('wp_dashboard_setup', 'pcg_debug_info');

Performance Profiling

Query Monitoring

// Monitor database queries
add_action('pre_get_posts', function() {
    if (defined('PCGUTEN_DEBUG')) {
        add_filter('query', function($query) {
            if (strpos($query, 'pcguten') !== false) {
                error_log('PCG Query: ' . $query);
            }
            return $query;
        });
    }
});

Memory Profiling

// Track memory usage
add_action('pcguten_before_scan', function() {
    if (defined('PCGUTEN_DEBUG')) {
        $memory_start = memory_get_usage(true);
        error_log('PCG Scan Start Memory: ' . size_format($memory_start));
    }
});

🆘 Getting Help

Self-Service Resources

  1. Plugin Documentation: Review all feature guides
  2. WordPress.org Forums: Search existing topics
  3. GitHub Issues: Check for known bugs
  4. Community Discord: Real-time help from users

Contacting Support

Information to Include

When contacting support, please provide:

System Information:

  • WordPress version
  • PHP version
  • Plugin version
  • Active theme
  • List of active plugins

Error Details:

  • Complete error messages
  • Steps to reproduce
  • Screenshots/screen recordings
  • Browser console errors

Debug Logs:

  • WordPress debug log excerpt
  • Plugin-specific logs
  • Server error logs

Debug Package Creation

# Create comprehensive debug package
wp plugin list --status=active > active-plugins.txt
wp theme list --status=active > active-theme.txt
wp option get PCGUTEN_license_status > license-status.txt
tail -50 /wp-content/debug.log > recent-errors.txt

Emergency Fixes

Disable Plugin Quickly

// If plugin causes site issues, add to wp-config.php
define('PCGUTEN_DISABLE', true);

Reset Plugin Data

-- Emergency database reset
DROP TABLE IF EXISTS wp_pcguten_classes;
DROP TABLE IF EXISTS wp_pcguten_scan_paths;
DELETE FROM wp_options WHERE option_name LIKE 'PCGUTEN_%';
DELETE FROM wp_options WHERE option_name LIKE 'pcguten_%';

Safe Mode Testing

  1. Switch to default WordPress theme
  2. Deactivate all other plugins
  3. Test plugin functionality
  4. Reactivate plugins/theme one by one