Kentico Troubleshooting: Common Issues and Fixes | OpsBlu Docs

Kentico Troubleshooting: Common Issues and Fixes

Solutions to common issues with Kentico Xperience including performance optimization and tracking problems

This guide helps you diagnose and fix common issues with Kentico Xperience websites, focusing on performance optimization and analytics tracking.

Quick Reference

Performance Issues

Tracking Issues

Common Issue Categories

Performance & Core Web Vitals

Kentico is a .NET-based platform that requires optimization for optimal Core Web Vitals scores:

Common Issues:

Quick Wins:

  1. Enable output caching
  2. Optimize media library images
  3. Use CDN for static assets
  4. Minimize ViewState usage
  5. Implement lazy loading

Analytics Tracking

Common Issues:

  • Tags not loading on specific page types
  • E-commerce events not firing
  • Duplicate tracking calls
  • Missing data in reports
  • Staging environment tracking production

Quick Checks:

  1. Verify tracking code in layout files
  2. Check browser console for errors
  3. Use tag debugging tools
  4. Review conditional loading logic
  5. Test in GTM Preview mode

Diagnostic Tools

Built-in Kentico Tools

1. Debug Mode

Enable Kentico debug mode to identify performance bottlenecks:

<!-- web.config -->
<configuration>
  <appSettings>
    <add key="CMSDebugEverything" value="true" />
    <add key="CMSDebugFiles" value="true" />
    <add key="CMSDebugSQL" value="true" />
    <add key="CMSDebugCache" value="true" />
  </appSettings>
</configuration>

Access debug panel: yoursite.com?debug=1

2. System Application Logs

Check for errors:

  • Event Log: System → Event log
  • Review errors and warnings
  • Filter by time period and severity

3. Health Monitoring

Monitor system health:

  • System → Health monitoring
  • Check:
    • Application performance
    • Database performance
    • Cache statistics
    • Request processing time

External Tools

Google PageSpeed Insights

Google Tag Assistant

  • Chrome extension for tag debugging
  • Validates GTM, GA4, Meta Pixel
  • Shows tag firing sequence
  • Identifies configuration errors

Chrome DevTools

  • Network tab for resource loading
  • Performance tab for Core Web Vitals
  • Console for JavaScript errors
  • Application tab for cookies/storage

Performance Optimization Checklist

Server-Side Optimization

  • Enable output caching for pages
  • Configure SQL Server performance
  • Optimize database indexes
  • Enable compression (Gzip/Brotli)
  • Use full-page caching when possible
  • Optimize ViewState (Portal Engine)
  • Review expensive macros
  • Implement partial caching for web parts

Client-Side Optimization

  • Minify CSS and JavaScript
  • Combine resource files
  • Use browser caching headers
  • Implement lazy loading for images
  • Optimize Media Library images
  • Load scripts asynchronously
  • Remove unused CSS/JS
  • Use image CDN

Database Optimization

  • Rebuild database indexes regularly
  • Archive old event log entries
  • Clean up staging tasks history
  • Optimize custom queries
  • Use database caching
  • Monitor slow queries
  • Update statistics

Tracking Troubleshooting Checklist

Basic Checks

  • Tracking code present in page source
  • Tracking ID/Container ID is correct
  • No JavaScript errors in console
  • Tags load in correct order
  • Environment checks not blocking
  • Consent management not preventing load
  • Ad blockers disabled for testing

GTM-Specific

  • Container published (not just saved)
  • Triggers configured correctly
  • Variables populated with values
  • No tag firing conflicts
  • Data layer structure correct
  • Preview mode shows tags firing

GA4-Specific

  • Measurement ID format correct (G-XXXXXXXX)
  • Config tag fires on all pages
  • Event names match conventions
  • Parameters have correct data types
  • DebugView shows events
  • Realtime report shows activity

Meta Pixel-Specific

  • Pixel ID correct (15-16 digits)
  • Base code loads before events
  • Meta Pixel Helper shows no errors
  • Events appear in Events Manager
  • Parameters formatted correctly
  • No duplicate pixels

Common Error Messages

Kentico-Specific Errors

"ViewState validation error"

Cause: ViewState tampering or timeout (Portal Engine)

Solution:

<!-- web.config -->
<pages enableViewStateMac="true" viewStateEncryptionMode="Always">
  <namespaces>
    <add namespace="System.Web.Mvc" />
  </namespaces>
</pages>

"The page has been changed by another user"

Cause: Content locking or concurrent editing

Solution:

  • Check out and check in the document
  • Clear browser cache
  • Check workflow status

"SQL timeout exception"

Cause: Slow database query or connection

Solution:

<!-- ConnectionStrings.config -->
<add name="CMSConnectionString"
     connectionString="...;Connection Timeout=120;" />

JavaScript Errors

"gtag is not defined"

Cause: GA4 script not loaded

Solution:

  • Verify script is in <head>
  • Check for JavaScript errors blocking execution
  • Ensure script loads before event code

"fbq is not defined"

Cause: Meta Pixel not loaded

Solution:

  • Verify pixel base code is present
  • Check loading order
  • Look for Content Security Policy blocking

"dataLayer is not defined"

Cause: GTM not loaded or data layer pushed too early

Solution:

// Always initialize
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({ /* data */ });

Environment-Specific Issues

Staging vs Production

Problem: Tracking fires on staging environment

Solution:

@{
    var isProduction = SiteContext.CurrentSite.SiteName == "ProductionSite";
    var trackingEnabled = SettingsKeyInfoProvider.GetBoolValue("EnableTracking", SiteContext.CurrentSiteID);
}

@if (isProduction && trackingEnabled)
{
    <!-- Tracking code here -->
}

Multi-Site Issues

Problem: Wrong tracking IDs on different sites

Solution:

@{
    // Get site-specific settings
    var siteId = SiteContext.CurrentSiteID;
    var gtmId = SettingsKeyInfoProvider.GetValue("GoogleTagManagerID", siteId);
}

Caching Issues

Output Caching Problems

Problem: Cached pages show old tracking codes

Solution:

  1. Clear output cache: System → Clear cache
  2. Exclude tracking code from caching:
<!-- This won't be cached -->
<% Response.WriteSubstitution(GetTrackingCode); %>

@functions {
    public static string GetTrackingCode(HttpContext context)
    {
        // Return tracking code
        return "<!-- tracking code -->";
    }
}

Browser Caching

Problem: Old scripts cached in browser

Solution:

  • Add version parameter to scripts
  • Set appropriate cache headers
  • Use cache busting: script.js?v=2.0

Portal Engine vs MVC Differences

Tracking Implementation

Aspect Portal Engine MVC
Layout location Master pages _Layout.cshtml
Code access Web Parts Controllers/Views
Macro usage Extensive Limited
ViewState Present Not applicable
Performance Slower Faster

Migration Considerations

When moving Portal Engine to MVC:

  • Reimplement web parts as widgets/sections
  • Convert macros to Razor syntax
  • Remove ViewState dependencies
  • Update tracking code placement
  • Test all tracking events

Getting Help

Kentico Resources

Analytics Resources

When to Contact Support

Contact Kentico support if:

  • System errors in event log
  • Database corruption issues
  • Licensing problems
  • Upgrade/migration issues
  • Performance degradation after updates

Performance Monitoring

Set Up Monitoring

  1. Application Insights (Azure)

    • Monitor server performance
    • Track exceptions
    • Analyze request metrics

  2. Google Analytics

    • Track page load times
    • Monitor Core Web Vitals
    • Analyze user experience

  3. New Relic / Datadog

    • APM for .NET applications
    • Database query monitoring
    • Custom instrumentation

Key Metrics to Monitor

  • TTFB: < 600ms (good)
  • LCP: < 2.5s (good)
  • FID/INP: < 100ms (good)
  • CLS: < 0.1 (good)
  • Server CPU: < 70%
  • Database response: < 100ms

Preventive Maintenance

Regular Tasks

Weekly:

  • Check event log for errors
  • Review health monitoring
  • Monitor disk space

Monthly:

  • Clear old event log entries
  • Archive staging tasks
  • Review performance metrics
  • Update tracking documentation

Quarterly:

  • Rebuild database indexes
  • Review and optimize queries
  • Update Kentico (minor versions)
  • Security patch installation

Annually:

  • Major version upgrades
  • Performance audit
  • Security audit
  • Tracking audit

Best Practices

  1. Use Staging Environment: Always test changes before production
  2. Enable Logging: Keep logs for troubleshooting
  3. Monitor Performance: Regular performance checks
  4. Document Changes: Keep change log for tracking implementations
  5. Test Thoroughly: Test all scenarios before deployment
  6. Use Version Control: Track all code changes
  7. Regular Backups: Database and file system backups
  8. Stay Updated: Keep Kentico and libraries updated

Next Steps

Based on your issue, refer to the specific troubleshooting guide:

Additional Resources

返回顶部