> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pureclarity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WooCommerce Troubleshooting Guide

> Common issues and solutions for PureClarity WooCommerce integration including installation, feeds, zones, and performance problems

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

## 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

<Warning>
  Always backup your site before installing or updating plugins. Test changes in a staging environment when possible.
</Warning>

### 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

<Info>
  Account setup typically completes within 2-5 minutes. Extended delays may indicate server connectivity issues.
</Info>

## Data Feed Problems

### Feed Failures

**Issue: Feeds not running automatically**

**Check Cron Configuration:**

```php theme={null}
// 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

<Tip>
  Enable debug logging in plugin settings to get detailed information about feed processing and identify specific issues.
</Tip>

### 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

<Warning>
  New installations require 24-48 hours for the AI to learn customer patterns and generate quality recommendations.
</Warning>

### 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:**

```php theme={null}
// 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

<Info>
  Most theme compatibility issues can be resolved with minor CSS adjustments. Contact our support team for theme-specific guidance.
</Info>

## 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:**

```sql theme={null}
-- 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

<Warning>
  Database modifications should only be performed by experienced administrators with proper backups in place.
</Warning>

## 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:**

* Email: [support@pureclarity.com](mailto:support@pureclarity.com)
* Support portal through PureClarity admin
* Emergency escalation for critical issues

**What to Include:**

* Detailed problem description
* Error messages and log entries
* Screenshots or screen recordings
* System configuration details
* Previous troubleshooting attempts

<Tip>
  The more specific information you provide, the faster our support team can identify and resolve your issue.
</Tip>

## 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

## Related Resources

* [WooCommerce Installation Guide](/integrations/woocommerce/installation)
* [Settings Configuration](/integrations/woocommerce/settings)
* [Data Feeds Management](/integrations/woocommerce/data-feeds)
* [Zone Configuration](/integrations/woocommerce/zones)
* [Dashboard Overview](/integrations/woocommerce/dashboard-overview)