Skip to main content
ModPageSpeed 2.0 and mod_pagespeed 1.1 — Coming Soon

Troubleshooting

Diagnose and fix common mod_pagespeed 1.1 issues. Missing response headers, broken pages, 404 errors on optimized resources, cache problems, and debugging.

No X-Mod-Pagespeed or X-Page-Speed header

Cause: mod_pagespeed is not running or not intercepting the response.

Fix:

  • Verify the module is loaded: check nginx -V for the module.
  • Verify pagespeed on; is set in your server block.
  • Check that the response Content-Type is text/html. mod_pagespeed only rewrites HTML responses.
  • Verify the module is loaded: check apachectl -M for pagespeed_module.
  • Verify ModPagespeed on is set.
  • Verify AddOutputFilterByType MOD_PAGESPEED_OUTPUT_FILTER text/html is present (usually set automatically).
  • Check that the response Content-Type is text/html. mod_pagespeed only rewrites HTML responses.
  • Open IIS Manager and verify the module appears under Modules for your site.
  • Verify pagespeed on is set in your pagespeed.config.
  • Check that the response Content-Type is text/html. mod_pagespeed only rewrites HTML responses.
  • Check the Windows Event Viewer (Windows Logs > Application) for startup errors from the mod_pagespeed source.
  • Verify that the IIS worker process (app pool identity) can read the pagespeed.config file.

Pages show X-Mod-Pagespeed / X-Page-Speed: MISS on every request

Cause: Resources are being optimized but the cache is not warming.

Fix:

  • First requests always show MISS. Wait for the rewrite to complete and retry.
  • If MISS persists, check cache directory permissions and disk space.
  • Verify the cache path exists and is writable by the web server process.

Optimized resources return 404

Cause: The .pagespeed. URL pattern is not being routed to mod_pagespeed.

Fix:

Ensure the .pagespeed. location block is present and appears before other location blocks that might match.

If using mod_rewrite, add RewriteCond %{REQUEST_URI} !\.pagespeed\. to prevent rewrite rules from intercepting pagespeed URLs.

Check that URL Rewrite rules (if installed) do not intercept .pagespeed. URLs. Add a stop-processing rule before other rewrite rules:

<rule name="PageSpeed" stopProcessing="true">
    <match url="\.pagespeed\." />
    <action type="None" />
</rule>

Also verify that the IIS app pool has not been recycled mid-optimization. The module reloads its cache on app pool restart, but in-flight rewrites are lost.

Verify that the configuration options match between the HTML-serving VHost and the resource-serving VHost.

mod_pagespeed broke my page layout or JavaScript

Cause: A filter is incompatible with your site’s CSS or JavaScript.

Fix:

  1. Identify which filter causes the issue by adding ?PageSpeed=off to the URL to disable all optimization.
  2. If the page works with ?PageSpeed=off, narrow down the filter by disabling them one at a time.
  3. Common culprits:
    • defer_javascript — breaks scripts using document.write or expecting to run during parse.
    • combine_javascript — can break order-dependent scripts.
    • prioritize_critical_css — can cause flash of unstyled content if critical CSS detection is incomplete.
  4. Disable the offending filter with DisableFilters.

mod_pagespeed is not picking up file changes

Cause: Resources are cached with their original TTL or mod_pagespeed’s implicit cache TTL.

Fix:

  • Flush the cache: curl 'http://yoursite.com/pagespeed_admin/cache?purge=*'
  • Or touch the cache.flush file (legacy method).
  • If resources are loaded from disk via LoadFromFile, changes are picked up after LoadFromFileCacheTtlMs expires (default: same as ImplicitCacheTtlMs, 5 minutes).
  • For immediate pickup, set a shorter ImplicitCacheTtlMs or purge the specific URL.

High memory usage

Cause: mod_pagespeed caches metadata and optimized resources in memory.

Fix:

  • Reduce LRUCacheKbPerProcess (default: 1024 Apache, 8192 nginx).
  • Reduce DefaultSharedMemoryCacheKB (default: 50000).
  • If using IPRO on a site with many unique uncacheable URLs, the metadata cache can grow. Consider disabling IPRO for those URL patterns.

SELinux blocks mod_pagespeed

Cause: SELinux policy prevents the web server from writing to the cache directory.

Fix:

sudo chcon -R -t httpd_sys_content_t /var/cache/pagespeed/

Beacons causing unexpected POST requests

Cause: Filters like lazyload_images, defer_javascript, and prioritize_critical_css use a JavaScript beacon to report client-side data. The beacon sends POST requests to the beacon URL.

Fix:

  • This is expected behavior, not an error.
  • If you do not use beacon-dependent filters, you can disable the beacon: pagespeed CriticalImagesBeaconEnabled false;
  • To suppress the <noscript> redirect tag inserted by some filters: pagespeed SupportNoScriptEnabled false;

How to get more diagnostic information

  • Check the admin page at /pagespeed_admin/ for statistics, active filters, and cache status.
  • Enable message history: set MessageBufferSize to a non-zero value, then view messages at /pagespeed_admin/message_history.
  • Add the debug filter temporarily to see detailed rewriting information in HTML comments: pagespeed EnableFilters debug;
  • Check nginx error logs for mod_pagespeed messages.
  • Check the admin page at /pagespeed_admin/ for statistics, active filters, and cache status.
  • Enable message history: set MessageBufferSize to a non-zero value, then view messages at /pagespeed_admin/message_history.
  • Add the debug filter temporarily: ModPagespeedEnableFilters debug
  • Check Apache error logs for mod_pagespeed messages.
  • Windows Event Viewer: Open Event Viewer and check Windows Logs > Application for warnings and errors from the mod_pagespeed source. The module logs startup issues, configuration errors, and runtime warnings here automatically.
  • Admin pages: Navigate to /pagespeed_admin/ for statistics, active filters, and cache status.
  • Message history: Set pagespeed MessageBufferSize 100000 in your config, then view messages at /pagespeed_global_admin/message_history. Messages are collected globally from all IIS worker processes.
  • DebugView: Use the Sysinternals DebugView tool for real-time debug output. Enable debug logging by adding pagespeed diagnose to your server-level pagespeed.config. In DebugView, enable Capture > Capture Global Win32 to see the output.
  • Debug filter: Add ?PageSpeedFilters=+debug to any URL to see detailed optimization decisions, timing data, and filter descriptions in HTML comments.
  • App pool permissions: Verify that the IIS app pool identity has read access to pagespeed.config and write access to the cache directory. Permission errors show up in Event Viewer.

See also