Skip to main content
When PureClarity zones aren’t displaying on your site, the issue typically involves cache settings, zone configuration, or widget setup. This guide provides systematic troubleshooting steps to identify and resolve zone display problems.

​
Quick Diagnosis Steps

Start with these immediate checks:
  • Recently added zones - Cache may need clearing
  • Module enabled - Verify PureClarity is active
  • Zone placement - Confirm widgets/HTML are correctly positioned
  • Active campaigns - Check PureClarity admin for campaign status
  • Network connectivity - Ensure connection to PureClarity servers

​
1. Clear Magento Caches

After adding new zones, specific caches must be cleared for zones to appear: Required cache types to clear:
  • Layouts - Template structure changes
  • Blocks HTML output - Cached HTML content
  • Page Cache - Full page caching
How to clear caches:
  1. Navigate to System > Cache Management
  2. Select required cache types
  3. Choose “Refresh” from Actions dropdown
  4. Click Submit
Magento cache management showing cache types to clear for zones Alternatively, use command line: 
php bin/magento cache:clean layout block_html full_page
Cache clearing is essential after any zone-related changes, including widget creation, template modifications, or configuration updates.

​
2. Disable Cache for Testing

Temporarily disable caching to isolate cache-related issues:
  1. Navigate to System > Cache Management
  2. Disable Layout, Block HTML, and Page Cache
  3. Test zone display
  4. Re-enable caches after testing
Only disable caches temporarily for testing. Running production sites without cache significantly impacts performance.

​
Zone Debug Investigation

​
3. Enable Zone Debug Mode

Use debug mode to visualize zone placement and identify issues:
  1. Navigate to Stores > Configuration > PureClarity > Advanced
  2. Set Debug Mode to “Yes”
  3. Save configuration
  4. Clear layout and block HTML caches
  5. Visit pages where zones should appear
Zone debug mode enabled in PureClarity advanced configuration What debug mode shows:
  • Zone placeholders with zone IDs when zones are placed but not populated
  • Zone positions for layout verification
  • Zone identification for campaign matching
For detailed debug mode usage, see Zone Debug Mode Guide.

​
4. Interpret Debug Output

If you see zone debug information:
  • ✅ Zone placement is correct
  • ❌ Zone content isn’t loading
  • Next step: Check campaign configuration
If you don’t see any debug information:
  • ❌ Zone placement problem
  • Next step: Verify widget/HTML configuration
Debug mode only shows zones that are properly placed but not receiving content. Missing debug output indicates placement issues.

​
Configuration Verification

​
5. Check Module Status

Verify PureClarity module is enabled:
  1. Navigate to Stores > Configuration > PureClarity > Environment & Credentials
  2. Confirm Enabled is set to “Yes”
  3. Save configuration if changes made
  4. Clear configuration cache
PureClarity module enabled setting in environment configuration If module is disabled:
  • Zones won’t display regardless of other settings
  • JavaScript won’t load for client-side zones
  • Server-side processing won’t occur
For configuration details, see Environment & Credentials.

​
6. Verify Credentials

Check that connection credentials are correct: Required fields:
  • Access Key - Must match PureClarity account
  • Secret Key - Must be current and valid
  • Region - Must match account region (USA/Europe)
Testing connectivity:
  1. Save configuration with correct credentials
  2. Run manual feeds to test connection
  3. Check feed status for authentication errors
  4. Monitor error logs for connection issues
Incorrect credentials prevent zones from loading content even if properly placed. Always verify credentials after configuration changes.

​
Widget Configuration Issues

​
7. Review Widget Setup

Check widget configuration for zone placement issues:
  1. Navigate to Content > Widgets
  2. Locate PureClarity Zone widgets
  3. Edit widgets to verify configuration
Widget configuration checklist:
  • Zone ID matches campaign configuration
  • Store view assignment is correct
  • Layout updates target appropriate pages
  • Container selection is valid for theme
  • Widget status is enabled
PureClarity zone widget configuration showing key settings For complete widget setup instructions, see Adding Zones Using Widgets.

​
8. Validate Layout Updates

Review widget layout updates for proper page targeting: Common layout issues:
  • Incorrect page selection - Widget targets wrong pages
  • Invalid container - Container doesn’t exist in theme
  • Theme compatibility - Widget conflicts with theme structure
  • Sort order problems - Widget positioning conflicts
Testing layout updates:
  1. Create simple test widget with basic configuration
  2. Place on homepage for easy testing
  3. Clear caches and verify display
  4. Gradually add complexity to isolate issues

​
HTML Zone Issues

​
9. Verify HTML Syntax

For zones added via direct HTML integration: Check HTML syntax by display mode: Client-side mode: 
<div data-pureclarity="bmz:ZONE-ID;"></div>
Server-side mode: 
<div data-serverside-pureclarity="bmz:ZONE-ID" 
     data-pureclarity-bmz-id="ZONE-ID" 
     class="pc_bmz" />
Common HTML errors:
  • Wrong mode syntax - Using client-side HTML in server-side mode
  • Typos in attributes - Misspelled data attributes
  • Missing semicolon - Client-side syntax requires trailing semicolon
  • Incorrect zone ID - Mismatch with campaign configuration
For HTML integration details, see Adding Zones Using HTML.

​
10. Template Integration Issues

Check template file modifications: Validation steps:
  1. Verify template compilation - No syntax errors
  2. Check file permissions - Templates are readable
  3. Confirm template hierarchy - Correct template inheritance
  4. Test template logic - Conditional statements work correctly
Common template problems:
  • Syntax errors preventing compilation
  • Incorrect template paths - Files in wrong locations
  • Theme conflicts - Customizations conflict with theme updates
  • PHP errors - Logic errors in template modifications

​
Campaign Configuration

​
11. Verify Campaign Setup

Check PureClarity admin for campaign configuration: Campaign checklist:
  • Campaign is active and published
  • Zone IDs match widget/HTML configuration
  • Targeting rules include your test pages
  • Content is available for recommendations
  • Scheduling allows current display
Testing campaigns:
  1. Create simple test campaign with basic zone
  2. Use easily identifiable content
  3. Test on staging environment first
  4. Monitor campaign analytics for activity

​
12. Check Data Requirements

Ensure sufficient data exists for recommendations: Data requirements:
  • Product feed completed successfully
  • Category feed sent if using category recommendations
  • User data available for personalization
  • Historical orders for behavioral recommendations
Feed validation:
  1. Check feed status in Magento dashboard
  2. Review feed logs for completion
  3. Verify data in PureClarity admin
  4. Test with different recommendation types

​
Network and Performance Issues

​
13. Test Network Connectivity

Verify connection to PureClarity servers: Browser testing:
  1. Open browser developer tools
  2. Visit page with zones
  3. Check Network tab for PureClarity requests
  4. Look for failed requests or timeouts
Common network issues:
  • Firewall blocking PureClarity domains
  • DNS resolution problems
  • SSL certificate validation issues
  • Timeout settings too restrictive

​
14. Performance Considerations

Check for performance-related zone issues: Performance factors:
  • Page load speed affecting JavaScript execution
  • Server response time for server-side zones
  • Memory limitations during zone processing
  • Third-party conflicts with other JavaScript
Performance testing:
  1. Test on fast connection to isolate network issues
  2. Disable other extensions temporarily
  3. Monitor server resources during zone loading
  4. Use simple zone configurations for testing

​
Advanced Troubleshooting

​
15. JavaScript Console Errors

Check browser console for JavaScript errors: Common JavaScript issues:
  • Script loading failures - PureClarity JavaScript not loading
  • Conflicts with other scripts - JavaScript errors preventing execution
  • Browser compatibility - Unsupported JavaScript features
  • Content Security Policy restrictions
Console debugging:
  1. Open browser developer tools
  2. Check Console tab for errors
  3. Look for PureClarity-related error messages
  4. Test with different browsers

​
16. Server-Side Debugging

For server-side mode implementations: Server-side troubleshooting:
  1. Check PHP error logs for processing errors
  2. Verify template rendering logic
  3. Test server-side requests to PureClarity
  4. Monitor server performance during zone processing

​
Resolution Workflow

​
Systematic Approach

  1. Clear caches - Start with cache-related fixes
  2. Enable debug mode - Visualize zone placement
  3. Verify configuration - Check module and credentials
  4. Test widgets/HTML - Validate zone placement code
  5. Check campaigns - Confirm PureClarity admin setup
  6. Test connectivity - Verify network communication

​
When Each Step Resolves Issues

  • Cache clearing → Zones appear after recent changes
  • Debug mode → Identifies placement vs content issues
  • Configuration fixes → Resolves module or credential problems
  • Widget/HTML fixes → Corrects placement issues
  • Campaign fixes → Resolves content delivery problems
  • Connectivity fixes → Solves network-related issues

​
Prevention and Best Practices

​
Development Workflow

  • Test in staging before production deployment
  • Clear caches after any zone-related changes
  • Use debug mode during development
  • Document zone placements for team reference

​
Monitoring Setup

  • Regular cache maintenance schedule
  • Zone performance monitoring
  • Campaign analytics review
  • Error log monitoring for zone issues

​
When to Contact Support

Contact PureClarity support when:
  • Systematic troubleshooting doesn’t resolve issues
  • Network connectivity problems persist
  • Complex campaign configuration needed
  • Custom implementation requires assistance
Information to provide:
  • Debug mode screenshots showing zone placement
  • Browser console error messages
  • Campaign configuration details
  • Recent changes to site or configuration

​
Zone Setup Guides

​
Configuration References

​
Other Troubleshooting