Umbraco Troubleshooting Overview
Common issues you may encounter with your Umbraco website and how to diagnose and fix them.
Performance Issues
Umbraco performance impacts user experience and SEO. Core Web Vitals are critical metrics.
Largest Contentful Paint (LCP)
LCP measures loading performance. Umbraco-specific LCP issues include:
- Unoptimized media (images)
- Heavy Razor view processing
- Uncached database queries
- External API calls in views
- Large JavaScript bundles
Target: LCP under 2.5 seconds
Cumulative Layout Shift (CLS)
CLS measures visual stability. Umbraco-specific CLS issues include:
- Images without dimensions
- Dynamic content loading
- Font loading issues
- Lazy-loaded components
Target: CLS under 0.1
General Performance Best Practices
Caching:
- Use Umbraco's output caching
- Implement distributed caching for multi-server
- Cache database queries and API responses
Media Optimization:
- Use Umbraco's image processor
- Implement lazy loading
- Serve responsive images
Code Optimization:
- Minimize Razor view complexity
- Use async/await for I/O operations
- Bundle and minify JavaScript/CSS
For general performance concepts, see the global performance hub.
Tracking & Analytics Issues
Events Not Firing
Common causes of tracking failures on Umbraco:
- Output caching including cached tracking data
- JavaScript errors in bundled scripts
- Content Security Policy blocking tracking
- SPA navigation not triggering pageviews
- Server-side rendering issues
Tracking Best Practices
Test Caching Impact:
- Verify tracking works with output caching enabled
- Use cache-busting for dynamic values
- Test authenticated vs. anonymous users
Monitor JavaScript Errors:
- Check browser console for errors
- Verify bundles load correctly
- Test across browsers
For general tracking concepts, see the global tracking issues hub.
Common Umbraco-Specific Issues
Output Caching Conflicts
Problem: Cached pages showing incorrect tracking data.
Fix:
- Move dynamic data to data layer
- Use donut caching for tracking sections
- Generate tracking code client-side
Content Security Policy
Problem: CSP blocking tracking scripts.
Fix:
- Add tracking domains to CSP whitelist
- Use nonce-based CSP
- Test in report-only mode first
Media Performance
Problem: Large images slowing page loads.
Fix:
- Use Umbraco's ImageSharp processor
- Implement responsive images
- Enable lazy loading
Debugging Tools
Umbraco Tools
Log Viewer: Settings > Log Viewer
Health Check: Settings > Health Check
Browser Developer Tools
- Console: Check for JavaScript errors
- Network: Verify tracking requests
- Application: Check cookies and storage
Performance Testing
- Google PageSpeed Insights
- GTmetrix
- Application Insights (Azure)