Before troubleshooting, ensure you have the latest version of the PureClarity WooCommerce plugin installed and that your WordPress/WooCommerce are up to date.

​
Common Installation Issues

​
Plugin Activation Problems

Issue: Plugin won’t activate
  • Verify WordPress version compatibility (5.0+)
  • Check WooCommerce is installed and active
  • Ensure sufficient server resources
  • Review plugin conflict with deactivation testing
Issue: White screen after activation
  • Check PHP error logs
  • Verify PHP version compatibility (7.4+)
  • Increase PHP memory limit
  • Contact hosting provider for server issues
Always backup your site before installing or updating plugins. Test changes in a staging environment when possible.

​
Account Connection Issues

Issue: Cannot connect to PureClarity account
  • Verify AccessKey and SecretKey are correct
  • Check selected region matches your account
  • Confirm account is active and in good standing
  • Test internet connectivity from server
Issue: Account setup timeout
  • Allow additional time for processing (up to 10 minutes)
  • Check server firewall settings
  • Verify outbound HTTP/HTTPS connections allowed
  • Contact support if persistent
Account setup typically completes within 2-5 minutes. Extended delays may indicate server connectivity issues.

​
Data Feed Problems

​
Feed Failures

Issue: Feeds not running automatically Check Cron Configuration: 
// Test WordPress cron in wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

// Check if cron is disabled
if (defined('DISABLE_WP_CRON') && DISABLE_WP_CRON) {
    // Cron is disabled - contact hosting provider
}
Common Solutions:
  • Verify WP-Cron is enabled on your server
  • Check hosting provider cron configuration
  • Review scheduled task logs
  • Test manual feed execution
Issue: Feed timeout errors Server Configuration:
  • Increase PHP max_execution_time (300+ seconds)
  • Raise PHP memory_limit (256MB+ recommended)
  • Optimize database queries
  • Contact hosting for server resources
Issue: Partial feed processing
  • Reduce batch size in settings
  • Check product data completeness
  • Verify image accessibility
  • Review error logs for specific failures
Enable debug logging in plugin settings to get detailed information about feed processing and identify specific issues.

​
Feed Data Issues

Issue: Products missing from recommendations
  • Verify products are published and visible
  • Check product has required fields (name, price, image)
  • Confirm product isn’t excluded by filters
  • Review inventory settings if applicable
Issue: Incorrect product information
  • Clear and regenerate product feeds
  • Check custom field mappings
  • Verify currency settings
  • Review product attribute configuration

​
Zone Display Problems

​
Zones Not Appearing

Issue: No recommendations showing Check Display Mode:
  1. Navigate to WooCommerce > PureClarity
  2. Verify Display Mode is set to “Live”
  3. Test in Test Mode as admin user
  4. Clear any caching plugins
Check Zone Configuration:
  • Verify zones are enabled in settings
  • Check theme compatibility
  • Review JavaScript console for errors
  • Test with default WordPress theme
Issue: Zones appear empty
  • Allow 24-48 hours for initial data processing
  • Check if products meet recommendation criteria
  • Verify customer has browsing history for personalization
  • Review segment targeting settings
New installations require 24-48 hours for the AI to learn customer patterns and generate quality recommendations.

​
Zone Performance Issues

Issue: Slow zone loading
  • Enable lazy loading for below-fold zones
  • Optimize image sizes and formats
  • Review zone product limits (4-8 recommended)
  • Check server response times
Issue: Zones affecting page layout
  • Review CSS conflicts with theme
  • Test responsive behavior on different devices
  • Adjust zone container settings
  • Consider custom CSS for integration

​
Performance and Compatibility

​
Server Performance

Issue: Site slowdown after installation Optimization Steps:
  • Enable WordPress object caching
  • Optimize database tables
  • Review plugin conflicts
  • Monitor server resource usage
PHP Configuration: 
// Recommended PHP settings
memory_limit = 256M
max_execution_time = 300
max_input_vars = 3000
post_max_size = 32M
upload_max_filesize = 32M

​
Theme Compatibility

Issue: Zones not displaying properly
  • Test with default WordPress theme
  • Review theme’s WooCommerce customizations
  • Check for JavaScript conflicts
  • Consider custom zone templates
Issue: Styling conflicts
  • Add custom CSS for PureClarity zones
  • Review theme’s CSS specificity
  • Test in different browsers
  • Check mobile responsiveness
Most theme compatibility issues can be resolved with minor CSS adjustments. Contact our support team for theme-specific guidance.

​
Advanced Troubleshooting

​
Debug Information Collection

Enable Detailed Logging:
  1. Go to WooCommerce > PureClarity > Settings
  2. Enable “Debug Logging”
  3. Reproduce the issue
  4. Check WooCommerce > Status > Logs
  5. Look for files prefixed with “pureclarity”
System Information:
  • WordPress version and installed plugins
  • WooCommerce version and active extensions
  • PHP version and server configuration
  • Theme name and version
  • Hosting provider and plan details

​
JavaScript Debugging

Browser Console Errors:
  1. Press F12 to open developer tools
  2. Navigate to Console tab
  3. Refresh page with issues
  4. Look for PureClarity-related errors
  5. Note error messages and line numbers
Common JavaScript Issues:
  • jQuery version conflicts
  • Other plugin JavaScript conflicts
  • Theme JavaScript errors
  • Content Security Policy restrictions

​
Database Issues

Issue: Database errors in logs Check Database Health: 
-- Check for corrupted tables
CHECK TABLE wp_pureclarity_delta;
REPAIR TABLE wp_pureclarity_delta;

-- Verify table structure
DESCRIBE wp_pureclarity_delta;
Database Optimization:
  • Optimize WooCommerce database tables
  • Clear expired transients
  • Review database error logs
  • Consider database repair tools
Database modifications should only be performed by experienced administrators with proper backups in place.

​
Getting Additional Help

​
Before Contacting Support

Gather Information:
  • Plugin version number
  • WordPress and WooCommerce versions
  • Error messages and screenshots
  • Steps to reproduce the issue
  • System information from WooCommerce status

​
Contact Options

Support Channels: What to Include:
  • Detailed problem description
  • Error messages and log entries
  • Screenshots or screen recordings
  • System configuration details
  • Previous troubleshooting attempts
The more specific information you provide, the faster our support team can identify and resolve your issue.

​
Preventive Maintenance

​
Regular Maintenance Tasks

Monthly:
  • Review feed processing logs
  • Check recommendation performance
  • Update plugin and dependencies
  • Monitor server resource usage
Quarterly:
  • Full system backup
  • Database optimization
  • Performance analysis
  • Security audit

​
Best Practices

Configuration Management:
  • Document custom settings
  • Test changes in staging environment
  • Maintain configuration backups
  • Review settings after updates
Monitoring:
  • Set up uptime monitoring
  • Track page load speeds
  • Monitor recommendation performance
  • Review error logs regularly