Sitecore Troubleshooting Overview | Blue Frog Docs

Sitecore Troubleshooting Overview

Troubleshoot common Sitecore issues including performance problems and tracking failures.

Sitecore Troubleshooting Overview

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

Performance Issues

Sitecore performance impacts user experience, SEO, and conversion rates. Core Web Vitals are critical metrics for Sitecore sites.

Largest Contentful Paint (LCP)

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

  • .NET server-side rendering time
  • Uncached Sitecore pages
  • Heavy ASPX/Razor view processing
  • Unoptimized images in Media Library
  • Experience Editor overhead
  • xDB tracking initialization delays

Target: LCP under 2.5 seconds

Cumulative Layout Shift (CLS)

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

  • Images without dimensions in Razor views
  • Personalized content loading late
  • Experience Editor placeholders shifting
  • Dynamic component rendering
  • Web fonts loading late

Target: CLS under 0.1

General Performance Best Practices

Caching:

  • Enable HTML cache in Sitecore
  • Configure output caching for renderings
  • Use Sitecore's caching API effectively
  • Implement Redis or SQL Server for cache storage

Image Optimization:

  • Use Media Library image processing
  • Configure proper image dimensions
  • Implement responsive images
  • Enable lazy loading

Code Optimization:

  • Minimize Sitecore API calls
  • Avoid expensive LINQ queries
  • Cache component output
  • Use asynchronous processing where possible

Database Performance:

  • Optimize indexes (rebuild regularly)
  • Configure connection pooling
  • Use Content Search API efficiently
  • Monitor SQL Server performance

For general performance concepts, see the global performance hub.

Tracking & Analytics Issues

Events Not Firing

Common causes of tracking failures on Sitecore:

  • Experience Editor blocking scripts
  • HTML cache including outdated tracking
  • Cookie consent blocking scripts
  • Rendering cache conflicts
  • xDB tracking disabled
  • Content Security Policy restrictions

Tracking Best Practices

Verify Installation:

  • Check tracking code in Razor views
  • Verify scripts load in normal mode only
  • Test with cleared HTML cache
  • Confirm not in Experience Editor

Cookie Consent Integration:

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

Sitecore Analytics Integration:

  • Verify xDB is enabled
  • Check Tracker is active
  • Confirm contact identification
  • Monitor session state

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

Common Sitecore-Specific Issues

HTML Caching Conflicts

Problem: Cached pages showing wrong tracking data or outdated content.

Fix:

// Clear HTML cache
Sitecore.Caching.CacheManager.GetHtmlCache(Sitecore.Context.Site).Clear();

// Or via Sitecore UI:
// Control Panel → Database → Clean up databases → HTML cache

Prevent:

  • Move dynamic data to client-side JavaScript
  • Disable caching for tracking renderings
  • Use VaryByData or VaryByUser for personalized content

Experience Editor Loading Issues

Problem: Tracking scripts breaking Experience Editor.

Fix:

@if (!Sitecore.Context.PageMode.IsExperienceEditorEditing)
{
    @* Tracking code here *@
}

Rendering Performance Issues

Problem: Slow page loads due to heavy rendering processing.

Diagnosis:

  1. Enable Sitecore debugging
  2. Check rendering times in logs
  3. Profile with Application Insights or New Relic

Fix:

<!-- Enable output caching for rendering -->
<renderingId cacheable="true" varyByData="true">
    <cacheKeyIndexing>true</cacheKeyIndexing>
</renderingId>

Publishing Delays

Problem: Content changes not reflecting on site.

Fix:

  1. Check publish status in Publishing tab
  2. Verify publishing target is "web" database
  3. Clear caches after publish
  4. Check if incremental publish failed (use republish)
// Programmatically clear caches
Sitecore.Caching.CacheManager.ClearAllCaches();

Media Library Image Issues

Problem: Images not loading or slow to render.

Causes:

  • Image processing errors
  • Missing media cache
  • Incorrect media URL generation

Fix:

<!-- Configure media settings -->
<setting name="Media.CacheEnabled" value="true"/>
<setting name="Media.MediaLinkServerUrl" value=""/>
<setting name="Media.RequestProtection.Enabled" value="true"/>

Clear media cache:

/sitecore/admin/cache.aspx

xDB Tracking Not Working

Problem: Analytics not being tracked in xDB.

Diagnosis:

// Check if Tracker is active
var isActive = Sitecore.Analytics.Tracker.Current?.IsActive ?? false;

// Check if session is initialized
var hasSession = Sitecore.Analytics.Tracker.Current?.Session != null;

Fix:

<!-- Ensure xDB is enabled -->
<setting name="Xdb.Enabled" value="true"/>
<setting name="Xdb.Tracking.Enabled" value="true"/>

Content Search Issues

Problem: Search results outdated or missing.

Fix:

  1. Rebuild search indexes
  2. Check index configuration
  3. Verify indexing strategy
// Rebuild index programmatically
var index = Sitecore.ContentSearch.ContentSearchManager.GetIndex("sitecore_web_index");
index.Rebuild();

Multi-Site Configuration Issues

Problem: Wrong site context or incorrect content loading.

Diagnosis:

// Check current site
var siteName = Sitecore.Context.Site?.Name;
var rootPath = Sitecore.Context.Site?.RootPath;

Sitecore.Diagnostics.Log.Info($"Site: {siteName}, Root: {rootPath}", this);

Fix:

  • Verify site definitions in web.config
  • Check hostName mappings
  • Ensure rootPath and startItem are correct

License Expiration

Problem: Site showing license errors or limited functionality.

Fix:

  1. Check license.xml file
  2. Verify expiration date
  3. Contact Sitecore support for renewal
  4. Restart application after updating license

Debugging Tools

Sitecore Tools

Sitecore Logs:

/App_Data/logs/

Monitor logs for errors:

Sitecore.Diagnostics.Log.Info("Custom log message", this);
Sitecore.Diagnostics.Log.Error("Error occurred", exception, this);

Administration Pages:

  • /sitecore/admin/cache.aspx - Cache management
  • /sitecore/admin/stats.aspx - Performance statistics
  • /sitecore/admin/showconfig.aspx - View merged configuration
  • /sitecore/admin/dbbrowser.aspx - Database browser

Sitecore Debugger: Enable in web.config:

<setting name="Debugging.Enabled" value="true"/>

Experience Editor: Use Experience Editor to test:

  • Component rendering
  • Personalization rules
  • Dynamic content
  • Preview mode vs. normal mode

Browser Developer Tools

  • Console: Check for JavaScript errors
  • Network: Verify tracking requests
  • Application: Check cookies and storage
  • Performance: Profile page load

Application Monitoring

Application Insights:

  • Track server-side performance
  • Monitor exceptions
  • Analyze dependencies

New Relic:

  • APM for .NET applications
  • Real user monitoring
  • Transaction tracing

Sitecore Experience Accelerator (SXA): Built-in diagnostics and debugging tools

Performance Testing

Sitecore-Specific Debugging

View Rendering Debug

Enable rendering diagnostics:

<setting name="Rendering.Diagnostics" value="true"/>

This adds HTML comments showing:

  • Rendering name
  • Data source
  • Caching status
  • Rendering time

Database Query Debugging

Enable SQL profiling:

<setting name="Counters.Enabled" value="true"/>

API Call Tracing

Monitor Sitecore API calls:

using (new Sitecore.Diagnostics.ProfileSection("My Operation"))
{
    // Your code here
}

Results appear in Sitecore logs.

Common Error Messages

"Item Not Found"

Cause: Missing content item or incorrect path

Fix:

  • Verify item exists in Content Editor
  • Check item path/ID
  • Ensure correct database (master vs. web)
  • Publish missing items

"Layout Not Found"

Cause: Layout definition missing or incorrect

Fix:

  • Check presentation details
  • Verify layout exists
  • Ensure layout is published
  • Reset layout to default

"Could not resolve host name"

Cause: Site definition misconfiguration

Fix:

  • Check site definitions in web.config
  • Verify hosts file (for local development)
  • Confirm DNS settings (for production)

"Access Denied"

Cause: Insufficient user permissions

Fix:

  • Check user roles and permissions
  • Verify item security
  • Grant appropriate access in Security Editor

Getting Help

Sitecore Resources

Support Channels

  • Sitecore Support Portal: Official support tickets
  • Partner Support: Through your Sitecore partner
  • Community Forums: Community-driven help
  • Training: Sitecore learning paths and certification

Best Practices

  1. Check Sitecore logs first - Most issues leave traces
  2. Clear caches - Many issues are cache-related
  3. Test in different modes - Preview, normal, Experience Editor
  4. Verify publishing - Ensure content is published to web
  5. Monitor performance - Use Application Insights or New Relic
  6. Keep updated - Apply Sitecore updates and patches

Next Steps

↑ Back to top
// SYS.FOOTER