Ezplatform Troubleshooting: Common Issues and Fixes | OpsBlu Docs

Ezplatform Troubleshooting: Common Issues and Fixes

Debug analytics issues on eZ Platform (Ibexa DXP) — Symfony cache layers, SiteAccess routing, Twig template inheritance, and HTTP cache tag invalidation.

eZ Platform (now Ibexa DXP) is a Symfony-based enterprise CMS with a multi-site architecture (SiteAccess), Twig templating, and built-in HTTP caching via Varnish or Fastly. Analytics issues on eZ Platform typically stem from the aggressive HTTP cache layer, SiteAccess routing affecting which templates load, or Twig block inheritance dropping script injections.

eZ Platform-Specific Debugging Approach

eZ Platform's architecture adds several layers between your template code and the visitor. The Symfony profiler in dev mode is essential for diagnosing where tracking code gets lost.

Enable Dev Mode for Diagnostics

# Switch to dev mode temporarily
# In .env or .env.local:
APP_ENV=dev
APP_DEBUG=1

# Clear cache after changing environment
php bin/console cache:clear

# Visit the site — the Symfony profiler toolbar appears at the bottom
# Check: Twig templates rendered, HTTP cache status, response headers

Check Varnish/HTTP Cache Status

# Check if Varnish is serving a cached page
curl -sI http://your-ez-site.com/ | grep -iE "x-cache|x-varnish|age|x-location-id"

# X-Cache: HIT means Varnish served this from cache
# X-Location-Id shows the eZ content location — useful for targeted purging

Verify SiteAccess Configuration

# Check which SiteAccess is active
php bin/console ezplatform:siteaccess:list

# Check SiteAccess matching rules
php bin/console debug:config ibexa.siteaccess

Most Common eZ Platform Analytics Issues

1. Varnish Serving Cached Pages Without Tracking Code

Symptoms: Analytics code visible when logged into the admin but not on the public site. Appears after purging cache.

Root cause: eZ Platform uses HTTP cache (Varnish/Fastly) by default. After adding tracking code to a template, cached pages still serve the old response.

Fix:

# Purge all Varnish cache
php bin/console fos:httpcache:invalidate:regex /

# Or purge specific content
php bin/console fos:httpcache:invalidate:tag location-2 content-type-1

# For Fastly
php bin/console fos:httpcache:invalidate:tag --provider=fastly location-2

2. SiteAccess Using Different Templates

Symptoms: Analytics works on the main site but not on subsites or language variants.

Root cause: eZ Platform's SiteAccess system can assign different template sets per SiteAccess. If your analytics code is only in one SiteAccess's templates, other SiteAccesses are untracked.

Diagnosis:

// Check which SiteAccess served the current page
console.log('SiteAccess:', document.querySelector('meta[name="ez-siteaccess"]')?.content || 'unknown');

Fix: Place analytics in a Twig template that all SiteAccesses inherit from:

{# In templates/themes/_base/pagelayout.html.twig #}
{% block head_script %}
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXX');
</script>
{% endblock %}

Then ensure all SiteAccess-specific templates extend this base:

# In config/packages/ibexa.yaml
ibexa:
    system:
        default:
            pagelayout: '@ibexadesign/pagelayout.html.twig'

3. Twig Block Override Dropping Scripts

Symptoms: Analytics present in the base layout but missing from pages that override the head block.

Root cause: Twig block inheritance. If a content type template overrides {% block head_script %} without {{ parent() }}, the base template's analytics code is lost.

Fix:

{# In content type-specific templates #}
{% block head_script %}
  {{ parent() }}
  {# Additional scripts for this content type #}
{% endblock %}

4. ESI (Edge Side Includes) Fragmenting Page Output

Symptoms: Analytics code intermittently appears or disappears. Page source shows <esi:include> tags.

Root cause: eZ Platform uses ESI blocks for personalized or dynamic content. If your analytics code is inside an ESI block, it's cached and served independently of the main page cache.

Fix: Keep analytics code outside ESI blocks. Place it directly in the base layout rather than in a sub-request or render(controller()) call:

{# GOOD: directly in the layout, not in an ESI block #}
{% block analytics %}
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
{% endblock %}

{# BAD: inside an ESI-capable sub-request #}
{{ render_esi(controller('App\\Controller\\AnalyticsController::trackAction')) }}

5. Content Preview / Admin Mode Inflating Data

Symptoms: Pageviews spike during content editing. Admin panel URLs appear in analytics reports.

Fix: Detect eZ Platform's preview/admin mode:

// Detect eZ Platform admin or preview mode
const isEzAdmin = window.location.pathname.startsWith('/admin') ||
  window.location.pathname.includes('/preview') ||
  document.querySelector('.ez-toolbar') !== null;

if (isEzAdmin) {
  window['ga-disable-G-XXXXXXX'] = true;
}

Environment Considerations

  • eZ Platform vs Ibexa DXP: The platform was rebranded to Ibexa DXP in 2021. Config file structures changed between eZ Platform 3.x and Ibexa DXP 4.x
  • Varnish required in production: eZ Platform's performance depends on Varnish. Without it, every request hits Symfony, which is slow and can cause analytics loading delays
  • Composer-managed: All bundles/extensions installed via Composer. Bundle conflicts can prevent the site from loading entirely
  • Symfony Flex recipes: Configuration files are scattered across config/packages/ directories. Check all SiteAccess-specific configs for template overrides

Performance Issues

  • LCP Issues - Varnish cache miss latency and Symfony controller rendering overhead
  • CLS Issues - Layout shifts from ESI block loading and personalized content swaps

Tracking Issues

  • Events Not Firing - Debug Varnish caching, SiteAccess routing, and Twig block inheritance
Back to top