Diagnosing Stable MODX Cache Causing Front‑End Content Not Updating

Problem Overview

After editing a template, chunk, or publishing a resource, the front‑end of a MODX site continues to show the old version. The manager preview may display the change, but anonymous visitors see stale output. This pattern points to the MODX cache not being invalidated.

Cause & Diagnostic Table

Observable Condition	Likely Cause	Quick Check
Front‑end shows old content while manager preview is correct	Cache lifetime too long or cache not flushed after change	Open the page in an incognito window; if content is stale, cache is suspect
Recent changes appear after a manual cache flush	Cache was not automatically cleared by the action that triggered the edit	Flush cache via manager and reload; if update appears, confirms cache issue
Only certain sections (e.g., a snippet output) are stale	Specific cache tag associated with that snippet was not cleared	Check the snippet’s cache tag in System → Cache → Cache Tags

Ordered Checks

1. Verify the symptom – Load the affected page in a private/incognito browser to avoid personal cookies. Note whether the content matches the manager preview.
2. Inspect cache status – In the MODX manager, go to System → Cache. Look at the Last flushed timestamp; if it predates your edit, the cache is stale.
3. Test a manual flush – Click Flush All (or flush the specific tag if known). Wait for the confirmation message.
4. Reload the front‑end – Refresh the page (hard reload: Ctrl+Shift+R) and check if the new content appears.
5. Check for errors – Review the manager’s Reports → Error Log and the web server logs for any cache‑related warnings after the flush.

Fixes Tied to Findings

• If the cache timestamp is old – Perform a full cache flush via manager (System → Cache → Flush All) or via CLI (see command below).
• If only a snippet or template is stale – Identify its cache tag (shown in the Cache tab) and flush that tag only: System → Cache → Flush by Tag.
• If automatic flushing is not happening – Review System Settings:
• cache_default_handler – ensure it is set to a working driver (e.g., file or memcache).
• cache_expires – consider lowering from the default 3600 seconds if content changes frequently.
• cache_sync_mode – set to 2 (sync on each request) for troubleshooting, then revert after confirming the issue.

Concrete Example – CLI Cache Flush

When you have SSH access to the server, you can flush the cache without opening the manager:

1. Log in as a user that can execute the PHP CLI (typically the same user that runs the web server, e.g., www-data or apache).
2. Run the MODX CLI script:

php /path/to/your/modx/core/cli.php msync -c

Where:

• /path/to/your/modx is the absolute path to your MODX installation.
• msync -c tells the script to clear all cache.
• Required permission: read/execute on the core/cli.php file and write permission on the cache directory (core/cache).
• Expected check: the command returns to the prompt with no error output. If you see PHP warnings, verify the PHP CLI version matches the web server’s version (≥7.2 for MODX 3.x).
• Risk: flushing the entire cache forces all visitors to regenerate cached output on the next request, which can cause a brief spike in CPU and I/O. Schedule during low‑traffic periods or use a tag‑specific flush (msync -t my_tag) to limit impact.

Verification

1. After the flush, reload the problematic page in an incognito tab.
2. Confirm that the updated markup, snippet output, or template change is visible.
3. Return to System → Cache and note that the Last flushed timestamp has updated to the current time.
4. Optionally, run php /path/to/modx/core/cli.php msync -c again and ensure no errors appear.

Limitations and Practical Checks

• Flushing cache does not address issues caused by external CDNs or browser caching; purge those layers separately if needed.
• If you use a custom cache driver (e.g., Redis), ensure the cache_default_handler setting points to a working class and that the daemon is reachable.
• To verify that automatic flushing works for future edits, make a test change, wait the usual interval, and check the front‑end without manually flushing. If the change appears, the auto‑flush mechanism is functional.

Escalation Criteria

• Content remains stale after a full cache flush and hard reload.
• Error logs show cache‑driver failures (e.g., "Unable to connect to Redis" or "File permission denied").
• The site experiences high load spikes after each flush, indicating the cache lifetime may be too short for traffic patterns.

In these cases, review the cache driver configuration, check file/system permissions, and consider adjusting cache_expires or implementing a more granular tag‑based flushing strategy within your custom snippets or plugins.