Concrete CMS Troubleshooting: Common Issues and Fixes | OpsBlu Docs

Concrete CMS Troubleshooting: Common Issues and Fixes

Troubleshoot Concrete CMS issues including slow page load, broken blocks, GA4 and GTM tracking failures, cache conflicts, and Core Web Vitals (LCP,...

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

Performance Issues

Concrete CMS performance directly impacts user experience, SEO rankings, and conversion rates. Core Web Vitals are critical metrics that affect both user satisfaction and search rankings.

Largest Contentful Paint (LCP)

LCP measures loading performance. Concrete CMS-specific LCP issues include:

  • Unoptimized block images
  • Heavy theme assets (CSS/JavaScript)
  • Render-blocking scripts in page templates
  • Marketplace add-on overhead
  • Database query performance
  • Full page caching misconfiguration

Target: LCP under 2.5 seconds

Cumulative Layout Shift (CLS)

CLS measures visual stability. Concrete CMS-specific CLS issues include:

  • Block content loading without dimensions
  • Dynamic blocks causing layout shifts
  • Font loading without proper fallbacks
  • Image blocks without explicit sizes
  • AJAX-loaded content

Target: CLS under 0.1

General Performance Best Practices

Theme Selection:

  • Use lightweight, modern themes
  • Avoid heavily customized legacy themes
  • Regularly update theme to latest version
  • Consider custom theme development for optimal performance

Block Management:

  • Audit blocks regularly
  • Remove unused blocks from pages
  • Minimize use of heavy blocks (carousels, sliders)
  • Use block caching where appropriate

Add-on Management:

  • Only install necessary marketplace add-ons
  • Remove unused add-ons completely (don't just uninstall)
  • Keep add-ons updated
  • Monitor add-on impact on performance

Image Optimization:

  • Use appropriate image formats (WebP with fallbacks)
  • Compress images before upload
  • Set explicit width and height attributes
  • Implement lazy loading for below-fold images
  • Use Concrete CMS's image thumbnail system

Code Optimization:

  • Minimize custom JavaScript in blocks
  • Use async/defer for non-critical scripts
  • Minimize and combine CSS files
  • Remove unused CSS and JavaScript
  • Leverage Concrete CMS asset system

Caching:

  • Enable full page caching for public pages
  • Use block caching strategically
  • Configure opcache properly
  • Use Redis or Memcached for object caching
  • CDN for static assets

Database Optimization:

  • Regular database maintenance
  • Optimize database tables
  • Index frequently queried columns
  • Clean up old page versions
  • Archive or delete unused pages

For general performance concepts, see the global performance hub.

Tracking & Analytics Issues

Events Not Firing

Common causes of tracking failures on Concrete CMS:

  • Tracking code loading in edit mode
  • JavaScript errors from blocks or add-ons
  • Ad blockers preventing pixel loads
  • Incorrect GTM container configuration
  • Data layer not properly initialized
  • Cache preventing script updates
  • Duplicate implementations causing conflicts

Common scenarios:

  • GA4 events missing from specific page types
  • Meta Pixel not tracking form submissions
  • GTM container not loading properly
  • Events firing multiple times (duplicate implementations)
  • Tracking working in view mode but not live

Tracking Best Practices

Implementation:

  • Use GTM as single source for all tags
  • Implement tracking at theme level for consistency
  • Exclude edit mode and dashboard from tracking
  • Test across all page types
  • Document all tracking implementations

Testing:

  • Use browser extensions (GTM debugger, GA debugger, Meta Pixel Helper)
  • Test in incognito/private browsing
  • Test across different browsers
  • Test on mobile devices
  • Verify in platform analytics (GA4, Meta Events Manager)
  • Test with cache enabled and disabled

Monitoring:

  • Set up alerts for tracking failures
  • Review data quality weekly
  • Monitor for JavaScript errors
  • Check conversion tracking accuracy
  • Review user flow data

For general tracking concepts, see the global troubleshooting hub.

Common Concrete CMS-Specific Issues

Cache Not Clearing

Problem: Changes don't appear after clearing cache.

Diagnosis:

  • Check if full page caching is enabled
  • Verify opcache is working
  • Check if CDN cache needs clearing
  • Browser cache may be caching old content

Fix:

  1. Dashboard → System & Settings → Optimization → Clear Cache
  2. Clear all cache types
  3. Clear browser cache
  4. If using CDN, purge CDN cache
  5. Restart PHP-FPM if necessary

Edit Mode vs. View Mode Differences

Problem: Site looks different in edit mode vs. view mode.

Causes:

  • CSS only loading in certain modes
  • JavaScript not running in edit mode
  • Blocks behaving differently
  • Cache issues

Fix:

  • Always test in view mode or logged out
  • Check theme's edit mode styles
  • Verify JavaScript doesn't conflict with edit mode
  • Clear cache and refresh

Blocks Not Appearing

Problem: Added blocks don't show on page.

Diagnosis:

  1. Check if block is in correct area
  2. Verify block type is installed
  3. Check page template includes area
  4. Look for JavaScript errors
  5. Check block permissions

Fix:

  • Verify block area name matches template
  • Reinstall block type if needed
  • Check browser console for errors
  • Verify user has permissions to see block

Form Submissions Not Working

Problem: Form block doesn't submit or email doesn't send.

Diagnosis:

  1. Check form block configuration
  2. Verify email settings
  3. Check spam filters
  4. Look for JavaScript errors
  5. Check server mail logs

Fix:

  • Dashboard → System & Settings → Email
  • Configure SMTP properly
  • Test with different email addresses
  • Check server PHP mail configuration
  • Review form notification settings

Marketplace Add-on Conflicts

Problem: Add-on causes errors or conflicts.

Diagnosis:

  1. Check error logs (/application/files/log/)
  2. Disable add-ons one at a time
  3. Check for JavaScript console errors
  4. Review add-on compatibility

Fix:

  • Update all add-ons to latest versions
  • Contact add-on developer
  • Use alternative add-on
  • Remove conflicting add-on

Theme Update Breaks Customizations

Problem: Theme updates overwrite custom code.

Prevention:

  • Don't edit core theme files directly
  • Create custom page templates
  • Use theme overrides in /application/
  • Document all customizations
  • Use version control (Git)
  • Test updates on staging site first

Recovery:

  • Restore from backup
  • Download previous theme version
  • Re-implement customizations
  • Move customizations to application folder

Page Versions Building Up

Problem: Too many page versions slowing database.

Fix:

  1. Dashboard → System & Settings → Optimization → Automated Jobs
  2. Enable "Remove Old Page Versions"
  3. Configure retention settings
  4. Run job manually to clean up immediately
  5. Set to run automatically

Database Connection Errors

Problem: "Unable to connect to database" errors.

Diagnosis:

  • Check database credentials in /application/config/database.php
  • Verify database server is running
  • Check max connections limit
  • Review error logs

Fix:

  • Verify database credentials correct
  • Restart database server
  • Increase max connections if needed
  • Check for long-running queries
  • Optimize database

White Screen of Death (WSOD)

Problem: Blank white page appears.

Diagnosis:

  1. Enable debug mode:
    • Edit /application/config/concrete.php
    • Set 'debug' => true
  2. Check error logs
  3. Check PHP error logs
  4. Look for fatal PHP errors

Common causes:

  • PHP memory limit exceeded
  • Fatal error in custom code
  • Add-on conflict
  • Missing required PHP extension

Fix:

  • Increase PHP memory_limit
  • Fix PHP errors
  • Disable problematic add-on
  • Clear cache
  • Restore from backup if needed

Debugging Tools

Browser Developer Tools

Chrome DevTools (F12):

  • Console: Check for JavaScript errors
  • Network: Verify tracking requests sent
  • Application: Check cookies, localStorage, session data
  • Performance: Analyze page load performance

Concrete CMS Debug Tools

Enable Debug Mode:

Edit /application/config/concrete.php:

return [
    'debug' => [
        'detail' => 'debug',
        'display_errors' => true,
    ],
];

Note: Disable on production sites after debugging.

View Error Logs:

/application/files/log/

Database Query Logging:

Enable in debug mode to see all database queries.

Analytics Debugging Tools

Browser Extensions:

Platform Tools:

  • GA4 DebugView
  • Meta Events Manager Test Events
  • GTM Preview Mode

Performance Testing Tools

Getting Help

Concrete CMS Community

Official Forums:

Concrete CMS Slack:

Documentation:

When to Hire a Developer

Consider hiring a Concrete CMS developer when:

  • Complex custom functionality needed
  • Multiple errors you can't resolve
  • Theme requires significant customization
  • Performance issues persist despite optimizations
  • Migration from another platform
  • Custom add-on development needed

Find Developers:

Next Steps

Performance Issues:

Tracking Issues:

Prevention:

  • Document your setup
  • Test before deploying
  • Monitor regularly
  • Keep Concrete CMS, themes, and add-ons updated
  • Use staging environment for testing
  • Implement regular backups
返回顶部