Contao Troubleshooting: Common Issues and Fixes | OpsBlu Docs

Contao Troubleshooting: Common Issues and Fixes

Debug analytics issues on Contao — page layout script injection, Symfony cache layers, insert tag processing, and multi-domain site configurations.

Contao is a PHP CMS built on Symfony that uses a page-layout-driven architecture. Unlike most CMS platforms where you edit templates directly, Contao manages script injection through its admin panel's page layouts and custom HTML modules. Analytics issues on Contao typically involve the page layout configuration, Contao's insert tag processing, or the Symfony-level caching.

Contao-Specific Debugging Approach

Contao separates page structure (layouts) from content (articles). Your analytics code must be placed in the correct layer — either the page layout or a custom HTML module assigned to a layout section.

Check Page Layout Configuration

The primary place for analytics code in Contao is the page layout's custom script fields:

  1. Log into Contao admin > Layout > Page layouts
  2. Edit your active layout
  3. Check Custom head tags and Custom body tags sections
  4. Verify the analytics code is present and unmodified
# Check rendered output for analytics tags
curl -s http://your-contao-site.com/ | grep -iE "gtag|gtm|analytics" | head -5

# Check Contao logs for template errors
tail -50 var/logs/contao-*.log | grep -i "error\|warning"

Debug Insert Tag Processing

Contao uses insert tags ({{tag::value}}) for dynamic content. If analytics code accidentally contains these patterns, Contao's parser will attempt to resolve them:

# Check if insert tag processing mangled your analytics code
curl -s http://your-contao-site.com/ | grep "{{" | head -5
# Any unresolved insert tags indicate a parsing issue

Most Common Contao Analytics Issues

1. Analytics Code in Wrong Page Layout

Symptoms: Tracking works on some pages but not others.

Root cause: Contao assigns page layouts at the page-tree level. Different sections of your site may use different layouts, and only the layout with the analytics code will track visitors.

Diagnosis:

// Check which layout is active on the current page
console.log('Page ID:', document.querySelector('body')?.id);
console.log('Layout class:', document.querySelector('body')?.className);

Fix: In Contao admin, go to Site structure and check the Layout assignment for each page tree branch. Either add analytics to all layouts, or create a shared analytics module included in every layout.

2. Contao Cache Serving Pages Without Tracking

Symptoms: Analytics code present in the admin but missing from the live page. Appears after clearing cache.

Root cause: Contao uses a multi-layer cache: Symfony HTTP cache, Contao's internal page cache, and optional reverse proxy support.

Fix:

# Clear all Contao caches
php vendor/bin/contao-console cache:clear
php vendor/bin/contao-console contao:cache:clear

# Or via admin: System > Maintenance > Purge cache

3. Insert Tags Breaking JavaScript Syntax

Symptoms: JavaScript errors in the console. Analytics code has unexpected content injected or portions are missing.

Root cause: If your analytics JavaScript contains {{ or }} patterns (such as in template literals or Mustache-style code), Contao's insert tag parser processes them before the page renders.

Fix: Avoid double-curly-brace patterns in Contao scripts, or escape them:

<!-- Instead of template literals with ${}, use string concatenation -->
<script>
// BAD - Contao may parse {{variable}}
// GOOD - use simple concatenation
var pageTitle = document.title;
gtag('event', 'page_view', {'page_title': pageTitle});
</script>

4. Multi-Domain Site Splitting Analytics Data

Symptoms: Analytics data is fragmented. Different domains or subdomains show separate GA sessions.

Root cause: Contao supports multi-domain site trees from a single installation. Each domain may have its own page tree and layout, and cross-domain tracking is not configured by default.

Fix: Configure cross-domain tracking in your analytics setup:

// In each page layout's head tags
gtag('config', 'G-XXXXXXX', {
  cookie_domain: 'auto',
  linker: {
    domains: ['www.domain1.com', 'www.domain2.com'],
    accept_incoming: true
  }
});

5. Contao Custom HTML Module Not Rendering

Symptoms: You created a custom HTML module with analytics code, assigned it to a layout section, but it does not appear.

Root cause: Contao modules must be assigned to an article area AND the article area must be included in the page layout. Missing either step results in no output.

Fix: Verify the complete chain:

  1. Content > Create/edit the custom HTML module with your analytics code
  2. Page layout > Ensure the layout section (e.g., "Header") includes the module's article area
  3. Site structure > Ensure the page uses the correct layout
  4. Check that the module is published (not hidden or scheduled)

Environment Considerations

  • Contao 4.x vs 5.x: Contao 5 requires PHP 8.1+ and uses Symfony 6. Some legacy analytics extensions may not be compatible
  • Contao Manager: Most Contao sites use the Contao Manager web interface instead of CLI. Cache clearing and extension management happen through the web UI
  • Symfony debug toolbar: Enable dev mode to see the Symfony profiler for detailed template and cache diagnostics
  • Shared hosting: Contao can run on shared hosting but cache clearing via CLI requires SSH access. Use the admin maintenance panel instead

Performance Issues

  • LCP Issues - Symfony cache warm-up and page layout rendering overhead
  • CLS Issues - Layout shifts from module-injected content and deferred custom elements

Tracking Issues

  • Events Not Firing - Debug page layout misassignment, cache layers, and insert tag processing
शीर्ष पर वापस जाएँ