Troubleshooting

Before You Start #

When experiencing issues with WooCommerce Shoppable Images, follow these preliminary steps:

1. Clear your browser cache and try again
2. Test in a different browser or incognito/private mode
3. Deactivate other plugins temporarily to check for conflicts
4. Switch to a default WordPress theme (like Twenty Twenty-Four) to rule out theme conflicts
5. Check that WooCommerce is active and up-to-date

Common Issues and Solutions #

Plugin Installation & Activation Issues #

Plugin Won’t Install #

Symptoms:

• “Installation failed” error message
• Plugin doesn’t appear in search results
• Upload fails with error message

Solutions:

1. Check WordPress version compatibility
   • Ensure you’re running WordPress 5.0 or higher
   • Update WordPress if necessary
2. Verify server requirements
   • PHP 7.4 or higher required
   • Adequate disk space available
   • Proper file permissions set
3. Try alternative installation method
   • If dashboard install fails, try uploading the .zip file
   • Use FTP upload as last resort
4. Contact hosting provider
   • Server may have restrictions on plugin installations
   • Memory limits may need adjustment

Plugin Activates But Doesn’t Work #

Symptoms:

• Plugin shows as active but no features work
• Menu items don’t appear
• Settings page not accessible

Solutions:

1. Verify WooCommerce dependency
   • WooCommerce must be installed and activated first
2. Check for PHP errors
   • Enable WordPress debug mode
   • Add to wp-config.php: define('WP_DEBUG', true);
   • Check error logs for specific issues
3. Regenerate permalinks
   • Go to Settings → Permalinks
   • Click “Save Changes” without making modifications

Shoppable Images Not Displaying #

Images Don’t Show on Frontend #

Symptoms:

• Shoppable images appear in admin but not on website
• Blank spaces where images should be
• Only regular images display without hotspots

Solutions:

1. Check theme compatibility
   • Switch to default theme temporarily
   • If it works, contact theme developer for compatibility
2. Verify image upload
   • Ensure images are properly uploaded to Media Library
   • Check image file formats (JPG, PNG, WebP supported)
   • Verify image file sizes aren’t too large
3. Clear caching
   • Clear any caching plugins
   • Clear CDN cache if using one
   • Clear browser cache
4. Check shortcode placement
   • Verify shortcodes are properly formatted
   • Ensure shortcodes are in content area, not widget areas

Hotspots Not Clickable #

Symptoms:

• Images display but clicking does nothing
• Hotspots visible but non-functional
• Products don’t open when clicked

Solutions:

1. JavaScript conflicts
   • Check browser console for JavaScript errors
   • Deactivate other plugins that might conflict
   • Test with default theme
2. CSS conflicts
   • Check if theme CSS is interfering
3. Product configuration
   • Verify linked products exist and are published
   • Check product visibility settings
   • Ensure products are in stock

WooCommerce Integration Problems #

Products Not Loading #

Symptoms:

• Can’t select products when creating hotspots
• Product search returns no results
• Error messages when trying to link products

Solutions:

1. WooCommerce status check
   • Go to WooCommerce → Status
   • Look for any critical issues
   • Update WooCommerce if outdated
2. Database permissions
   • Check if plugin has proper database access
   • Contact hosting provider if database errors occur
3. Product status verification
   • Ensure products are published, not drafts
   • Check product visibility settings
   • Verify products have prices set

Cart/Checkout Issues #

Symptoms:

• Products don’t add to cart when clicked
• Cart shows wrong quantities
• Checkout process fails

Solutions:

1. WooCommerce settings
   • Check WooCommerce → Settings → Products
   • Verify “Add to cart” behavior settings
   • Test with WooCommerce default settings
2. Session conflicts
   • Check for session-related plugin conflicts
   • Test with caching disabled
   • Clear all caches and cookies

Performance Issues #

Slow Loading Images #

Symptoms:

• Images take long time to load
• Page speed significantly reduced
• Timeout errors

Solutions:

1. Image optimization
   • Compress images before uploading
   • Use WebP format when possible
   • Limit image dimensions to maximum needed size
2. Caching configuration
   • Enable proper caching plugins
   • Configure CDN if available
   • Set appropriate browser caching headers
3. Server optimization
   • Check server response times
   • Consider upgrading hosting plan
   • Optimize database if needed

Mobile Responsiveness Issues #

Images Don’t Display Correctly on Mobile #

Symptoms:

• Images too large or small on mobile devices
• Hotspots misaligned on tablets/phones
• Touch interactions not working

Solutions:

1. Responsive settings
   • Check plugin’s mobile settings
   • Ensure responsive breakpoints are configured
   • Test on actual devices, not just browser resize
2. Theme compatibility
   • Verify theme is truly mobile-responsive
   • Check for CSS conflicts on mobile
   • Add custom mobile CSS if needed
3. Touch optimization
   • Ensure hotspots are large enough for touch
   • Test touch interactions on various devices
   • Check for touch event conflicts

Advanced Troubleshooting #

Enable Debug Mode #

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

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

Check debug logs at: /wp-content/debug.log

Plugin Conflict Testing #

1. Deactivate all plugins except WooCommerce and WP-Plugz Shoppable Images
2. Test functionality – if it works, you have a plugin conflict
3. Reactivate plugins one by one until the issue returns
4. Identify the conflicting plugin and seek compatibility solutions

Theme Conflict Testing #

1. Switch to default WordPress theme (Twenty Twenty-Four)
2. Test plugin functionality
3. If it works, the issue is theme-related
4. Contact theme developer or add custom CSS/JavaScript fixes

Database Issues #

If you suspect database corruption:

1. Backup your database first
2. Use phpMyAdmin to check plugin tables
3. Look for tables starting with your plugin prefix
4. Contact support if tables are missing or corrupted

Error Messages and Solutions #

“Fatal Error: Class Not Found” #

• Cause: Plugin files corrupted or incomplete
• Solution: Deactivate, delete, and reinstall plugin

“Memory Limit Exceeded” #

• Cause: Insufficient PHP memory
• Solution: Increase memory limit in wp-config.php or contact host

“Permission Denied” #

• Cause: File permission issues
• Solution: Set correct file permissions (644 for files, 755 for folders)

“AJAX Request Failed” #

• Cause: JavaScript/AJAX conflicts
• Solution: Check for JavaScript errors, test with default theme

Getting Additional Help #

Before Contacting Support #

1. Update everything:
   • WordPress core
   • WooCommerce plugin
   • WP-Plugz Shoppable Images plugin
   • Your theme
2. Gather information:
   • WordPress version
   • WooCommerce version
   • Plugin version
   • Theme name and version
   • List of active plugins
   • Error messages (exact text)
   • Screenshots of issues
3. Test in staging environment if possible

Support Channels #

• Free Version: Support is offered through wordpress.org
• Pro Version: coming soon

What to Include in Support Requests #

• Detailed description of the issue
• Steps you’ve already tried
• System information (WordPress, PHP, server details)
• Screenshots or screen recordings
• Error messages from debug logs
• URL where issue can be seen (if possible)

Prevention Tips #

1. Regular Updates: Keep WordPress, WooCommerce, and plugins updated
2. Staging Environment: Test changes before applying to live site
3. Regular Backups: Backup before making any changes
4. Monitor Performance: Use tools to track site speed and errors
5. Documentation: Keep notes of customizations and settings

Remember: Most issues can be resolved by methodically working through these troubleshooting steps. Start with the simplest solutions first before moving to more complex ones.