Modx Troubleshooting: Common Issues and Fixes

Troubleshoot common MODX issues including performance problems and tracking failures.

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

Performance Issues

MODX site performance directly impacts conversion rates and SEO. Core Web Vitals are critical metrics that affect both user experience and search rankings.

Largest Contentful Paint (LCP)

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

Template rendering and parsing overhead
Unoptimized images in chunks and TVs
Heavy plugins executing on OnWebPagePrerender
Uncached resources slowing page generation
Multiple database queries for TVs and snippets
External scripts in template head

Target: LCP under 2.5 seconds

Cumulative Layout Shift (CLS)

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

Images without dimensions in chunks
Dynamic content from snippets shifting layouts
Font loading in custom templates
JavaScript-based navigation menus
Uncached snippets causing variable load times

Target: CLS under 0.1

General Performance Best Practices

Template Optimization:

Use MODX caching effectively
Minimize uncached tags ([[!placeholder]])
Cache snippets when possible
Avoid deep nesting of snippets
Use static chunks for common elements

Resource Management:

Enable MODX cache for published resources
Set appropriate cache refresh intervals
Use partial cache clearing instead of full cache clears
Implement cache warming after updates

Database Optimization:

Index frequently queried TV fields
Optimize getResources queries with limits
Use prepare/process snippets for collections
Avoid n+1 query problems with TVs

Plugin Efficiency:

Audit plugins executing on each request
Disable unused system event bindings
Profile plugin execution time
Consider moving logic to snippets when appropriate

For general performance concepts, see the global performance hub.

Tracking & Analytics Issues

Events Not Firing

Common causes of tracking failures on MODX:

MODX placeholders not parsing correctly
JavaScript errors from template or plugins
Cache issues preventing dynamic values
Plugin execution order conflicts
Incorrect GTM container configuration
Data layer not populating before GTM
Multiple implementations causing conflicts

Common scenarios:

GA4 events showing MODX placeholders as literal text
Meta Pixel not tracking due to cached chunks
GTM container not loading on all templates
Events firing with cached data instead of current resource

Tracking Best Practices

Consolidate Tracking:

Use GTM as single source for all tags
Implement data layer in base template or plugin
Remove duplicate tracking code across templates
Document all tracking implementations

Test Thoroughly:

Clear MODX cache before testing
Use browser extensions (GTM debugger, GA debugger, Meta Pixel Helper)
Test in incognito/private browsing
Test across different templates and resources
Verify in platform analytics (GA4, Meta Events Manager)

Monitor Continuously:

Set up alerts for tracking failures
Review data quality weekly
Check for bot traffic in analytics
Monitor conversion tracking accuracy

For general tracking concepts, see the global troubleshooting hub.

Common MODX-Specific Issues

Problem: Changes not appearing on live site.

Diagnosis:

Check if MODX cache is enabled
Look for uncached tags that should be cached
Verify cache refresh settings

Fix:

Clear MODX cache: Manage → Clear Cache
Check template/resource cache settings
Use [[!uncached]] tags only when necessary
Clear browser cache (Ctrl+Shift+Delete)

Template Placeholders Not Parsing

Problem: MODX tags appear as literal text (e.g., [[*pagetitle]] shows on page).

Causes:

Incorrect tag syntax
Tag in cached chunk that shouldn't be cached
Template not saved properly
Parser disabled

Fix:

// Ensure correct syntax
[[*id]]          // Resource field ✓
{*id}           // Wrong ✗
[*id]           // Wrong ✗

// Use uncached if needed
[[!*pagetitle]]  // Uncached
[[*pagetitle]]   // Cached (default)

// Check output filters
[[*price:default=`0`]]              // With default
[[*tv:notempty=`[[*tv]]`:default=`N/A`]]  // Conditional

Plugin Conflicts

Problem: Plugins causing JavaScript errors or page issues.

Diagnosis:

Check MODX error log: Reports → Error Log
Open browser console (F12) for JavaScript errors
Disable plugins one at a time to identify culprit
Check plugin system events for conflicts

Fix:

Review plugin execution order
Ensure plugins don't duplicate functionality
Check for compatibility with MODX version
Update or remove problematic plugins
Contact plugin developer for support

Snippet Not Displaying

Problem: Snippet call returns nothing or shows error.

Causes:

Snippet name misspelled
Snippet not saved/installed
Error in snippet code
Missing required properties

Diagnosis:

// Check snippet is called correctly
[[!snippetName]]  // Uncached
[[snippetName]]   // Cached

// Check properties
[[!snippetName? &property=`value`]]

// Enable error reporting temporarily
[[!snippetName? &debug=`1`]]

Fix:

Verify snippet name in Elements → Snippets
Check snippet code for PHP errors
Check MODX error log
Test snippet with minimal properties
Review snippet documentation

Template Variables (TVs) Not Populating

Problem: TV values don't appear in tracking or on page.

Causes:

TV not assigned to template
TV not set on resource
Incorrect TV tag syntax
TV output type misconfigured

Fix:

// Ensure TV is assigned to template
// Elements → Templates → Template → Template Variables tab

// Check TV value exists
[[*tv_name:notempty=`[[*tv_name]]`:default=`Default Value`]]

// Raw value (no output formatting)
[[*tv_name:raw]]

// Specific output type
[[*tv_name:richtext]]

Multi-Context Issues

Problem: Tracking not working in all contexts.

Causes:

GTM/tracking code only in web context template
Context-specific settings not configured
Resources not loading correct template

Fix:

// Context-aware tracking
[[switch? &value=`[[!++context_key]]`
  &case=`web=GTM-AAAAAAA`
  &case=`mobile=GTM-BBBBBBB`
  &default=`GTM-AAAAAAA`
]]

// Or in plugin
$contextKey = $modx->context->get('key');
$gtmId = match($contextKey) {
    'web' => 'GTM-AAAAAAA',
    'mobile' => 'GTM-BBBBBBB',
    default => 'GTM-AAAAAAA'
};

Form Submissions Not Tracking

Problem: FormIt submissions not triggering analytics events.

Causes:

Form success condition not working
Event code not in correct location
Cache interfering with success detection

Fix:

// Ensure event fires on success
[[!+fi.successMessage:notempty=`
<script>
  // Your tracking event here
  gtag('event', 'form_submit', {...});
  fbq('track', 'Lead', {...});
</script>
`]]

// Or use custom FormIt hook
[[!FormIt?
  &hooks=`email,FormItSaveForm,customGAHook`
]]

Debugging Tools

MODX Built-in Tools

Error Log:

Reports → Error Log
Shows PHP errors, plugin errors, snippet failures

System Settings:

debug → Yes (temporarily for troubleshooting)
log_level → MODX_LOG_LEVEL_INFO or MODX_LOG_LEVEL_DEBUG

Cache Manager:

Manage → Clear Cache
Clear specific cache partitions
Refresh URIs

Browser Developer Tools

Chrome DevTools (F12):

Console: Check for JavaScript errors
Network: Verify analytics requests sent
Application: Check localStorage, cookies, session data
Elements: Inspect rendered HTML to see if MODX tags parsed

MODX-Specific Extensions

Console Plugin:

Debug output to screen or log
Performance monitoring
Variable inspection

Debug Plugin:

Shows MODX processing time
Lists executed snippets and plugins
Database query logging

Analytics Debugging Tools

Browser Extensions:

Platform Tools:

GA4 DebugView
Meta Events Manager Test Events
GTM Preview Mode

Performance Testing Tools

Google PageSpeed Insights
WebPageTest
GTmetrix
Chrome DevTools Lighthouse

Debugging Workflow

Step-by-Step Process

Identify the Issue
- What's not working?
- Where does it occur? (all pages, specific template, specific resource)
- When did it start?
Check MODX Logs
- Error log for PHP/plugin errors
- System log for MODX events
- Browser console for JavaScript errors
Clear Cache
- Clear MODX cache
- Clear browser cache
- Test in incognito mode
Isolate the Problem
- Disable plugins one by one
- Test with different template
- Check on different resource
- Compare working vs. non-working pages
Test Fix
- Implement solution
- Clear cache
- Test thoroughly
- Monitor for regressions
Document
- Note what was wrong
- Document solution
- Update documentation
- Share with team

Getting Help

MODX Community Resources

MODX Forums:

forums.modx.com
Active community
Search existing threads
Post with details (MODX version, PHP version, error messages)

MODX Documentation:

docs.modx.com
Official documentation
Tutorials and guides

MODX Slack:

Real-time community chat
Quick questions and answers

When to Hire a Developer

Consider hiring a MODX developer when:

Complex custom functionality needed
Multiple errors you can't resolve
Performance issues persist despite optimizations
Need custom snippet or plugin development
Migration or major upgrade required

Find MODX Developers:

MODX Professional Directory
MODX Slack #jobs channel
Freelance platforms (with MODX experience)

Support Channels

MODX Extras Developers:

Contact developer via MODX Forums
Check Extra repository for issues/documentation
Email support if provided

Hosting Provider:

Server configuration issues
PHP version compatibility
Database optimization
Performance tuning

Best Practices for Prevention

Regular Maintenance

Weekly: Review error logs
Monthly: Clear old cache files, review plugin performance
Quarterly: Update MODX core and extras, audit tracking implementation
Annually: Full performance audit, security review

Change Management

Test locally before deploying to production
Backup before major changes
Document all customizations
Version control for templates and custom code

Monitoring

Set up uptime monitoring
Monitor Core Web Vitals
Track analytics data quality
Log critical events

Next Steps

Performance Issues:

Tracking Issues:

Debug Events Not Firing

Prevention:

Document your setup
Test before deploying
Monitor regularly
Keep MODX and extras updated

返回顶部

Modx Troubleshooting: Common Issues and Fixes

Performance Issues

Largest Contentful Paint (LCP)

Cumulative Layout Shift (CLS)

General Performance Best Practices

Tracking & Analytics Issues

Events Not Firing

Tracking Best Practices

Common MODX-Specific Issues

Cache-Related Problems

Template Placeholders Not Parsing

Plugin Conflicts

Snippet Not Displaying

Template Variables (TVs) Not Populating

Multi-Context Issues

Form Submissions Not Tracking

Debugging Tools

MODX Built-in Tools

Browser Developer Tools

MODX-Specific Extensions

Analytics Debugging Tools

Performance Testing Tools

Debugging Workflow

Step-by-Step Process

Getting Help

MODX Community Resources

When to Hire a Developer

Support Channels

Best Practices for Prevention

Regular Maintenance

Change Management

Monitoring

Next Steps