TYPO3 Troubleshooting Overview

Common issues you may encounter with your TYPO3 website and how to diagnose and fix them.

Performance Issues

TYPO3 performance impacts user experience and SEO. Core Web Vitals are critical metrics.

Largest Contentful Paint (LCP)

LCP measures loading performance. TYPO3-specific LCP issues include:

• Uncached pages with heavy TypoScript
• Unoptimized FAL (File Abstraction Layer) images
• Complex Fluid template rendering
• Database-heavy content elements
• Extension-added JavaScript blocking render

Target: LCP under 2.5 seconds

Cumulative Layout Shift (CLS)

CLS measures visual stability. TYPO3-specific CLS issues include:

• Images without dimensions in Fluid templates
• Dynamic content loading
• Web fonts loading late
• Cookie consent banners

Target: CLS under 0.1

General Performance Best Practices

Caching:

• Enable page caching
• Use staticfilecache extension for static pages
• Configure proper cache headers
• Use Redis or Memcached for cache backend

Image Optimization:

• Use ImageMagick/GraphicsMagick processing
• Configure proper image dimensions
• Implement lazy loading
• Use WebP with fallbacks

Code Optimization:

• Minimize TypoScript complexity
• Avoid USER_INT where possible
• Optimize database queries in extensions
• Use Symfony profiler for debugging

For general performance concepts, see the global performance hub.

Tracking & Analytics Issues

Events Not Firing

Common causes of tracking failures on TYPO3:

• Page caching including outdated tracking
• Cookie consent blocking scripts
• TypoScript configuration errors
• Extension conflicts
• Content Security Policy issues

Tracking Best Practices

Verify Installation:

• Check TypoScript includes are loaded
• Verify extension is active
• Test with cleared cache

Cookie Consent Integration:

• Ensure tracking respects consent
• Test consent flow thoroughly
• Verify tracking fires after consent

For general tracking concepts, see the global tracking issues hub.

Common TYPO3-Specific Issues

Caching Conflicts

Problem: Cached pages showing wrong tracking data.

Fix:

• Move dynamic data to JavaScript data layer
• Use USER_INT for uncached tracking sections
• Clear all TYPO3 caches after changes

Extension Conflicts

Problem: Extensions causing errors or conflicts.

Diagnosis:

1. Check System > Log for errors
2. Disable extensions one by one
3. Check browser console

Fix:

• Update conflicting extensions
• Contact extension maintainer
• Check Forge/GitHub for known issues

TypoScript Not Loading

Problem: Tracking code not appearing on pages.

Fix:

1. Verify extension is installed and active
2. Check TypoScript includes in template
3. Clear caches and reload
4. Check page TSconfig overrides

Debugging Tools

TYPO3 Tools

Admin Panel: Enable in Install Tool to debug TypoScript and caching.

System > Log: Check for PHP errors and warnings.

Extension: adminpanel: Debug TypoScript rendering and cache status.

Browser Developer Tools

• Console: Check for JavaScript errors
• Network: Verify tracking requests
• Application: Check cookies

Performance Testing

• Google PageSpeed Insights
• GTmetrix
• TYPO3 System > Reports

Getting Help

• TYPO3 Documentation
• TYPO3 Slack
• TYPO3 Forge