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

# Zones Not Showing Troubleshooting

> Step-by-step guide to diagnose and fix issues when PureClarity zones aren't displaying on your Magento 2.x site

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

## Cache-Related Issues

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

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/cache-management-clear.webp" alt="Magento cache management showing cache types to clear for zones" />

Alternatively, use command line:

```bash theme={null}
php bin/magento cache:clean layout block_html full_page
```

<Note>
  Cache clearing is essential after any zone-related changes, including widget creation, template modifications, or configuration updates.
</Note>

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

<Warning>
  Only disable caches temporarily for testing. Running production sites without cache significantly impacts performance.
</Warning>

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

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/zone-debug-mode-enabled.webp" alt="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](/integrations/magento/magento-2/zone-debug).

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

<Tip>
  Debug mode only shows zones that are properly placed but not receiving content. Missing debug output indicates placement issues.
</Tip>

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

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/pureclarity-enabled-setting.webp" alt="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](/integrations/magento/magento-2/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

<Warning>
  Incorrect credentials prevent zones from loading content even if properly placed. Always verify credentials after configuration changes.
</Warning>

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

<img src="https://mintlify.s3.us-west-1.amazonaws.com/pureclarity/images/magento/zone-widget-configuration.webp" alt="PureClarity zone widget configuration showing key settings" />

For complete widget setup instructions, see [Adding Zones Using Widgets](/integrations/magento/magento-2/adding-zones-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:**

```html theme={null}
<div data-pureclarity="bmz:ZONE-ID;"></div>
```

**Server-side mode:**

```html theme={null}
<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](/integrations/magento/magento-2/adding-zones-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

## Related Resources

### Zone Setup Guides

* [Adding Zones Using Widgets](/integrations/magento/magento-2/adding-zones-widgets) - Widget-based zone placement
* [Adding Zones Using HTML](/integrations/magento/magento-2/adding-zones-html) - Direct HTML integration
* [Zone Debug Mode](/integrations/magento/magento-2/zone-debug) - Debug mode usage

### Configuration References

* [Environment & Credentials](/integrations/magento/magento-2/environment-credentials) - Basic configuration
* [Configuration Mode](/integrations/magento/magento-2/configuration-mode) - Client-side vs server-side
* [Dashboard Overview](/integrations/magento/magento-2/dashboard) - System monitoring

### Other Troubleshooting

* [Products Not Updating](/integrations/magento/magento-2/products-not-updating) - Data synchronization issues
* [Feed Troubleshooting](/integrations/magento/magento-2/feeds-failing-errors) - Feed-related problems