Skip to main content
ModPageSpeed 2.0: AVIF, WebP, and critical CSS — up to 69% less page weight on the live demo
2.0 1.15

Troubleshooting

Diagnose and fix common mod_pagespeed 1.15 issues. Missing response headers, broken pages, 404 errors on optimized resources, cache problems, debugging, and reading .pagespeed. URLs and data-pagespeed-url-hash markers.

On this page

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:
  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: 51200).
  • 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;

Reading a .pagespeed. URL and debug markers

When mod_pagespeed optimizes a resource, it rewrites the URL to a self-describing form:

originalName.pagespeed.FILTER_ID.HASH.extension

For example, styles.css.pagespeed.ce.GhT8kP2mNq.css.

  • FILTER_ID is a short code for the filter that produced the resource: ce (cache extension), ic (image rewriting), jm (JavaScript minification), cc (combined CSS), cf (CSS rewriting).
  • HASH is a hash of the optimized resource’s content. Because it is derived from the bytes, any content change yields a new URL. That is why extend_cache can serve a one-year Cache-Control lifetime without the URL ever going stale.

data-pagespeed-url-hash is a different hash

A data-pagespeed-url-hash attribute on an <img> tag is not the content hash above. It is a hash of the image’s original URL, inserted by the critical-image beacon so the beacon JavaScript can report which images rendered above the fold without parsing rewritten URLs. Seeing it, along with the beacon POSTs that go with it, is expected; see Beacons causing unexpected POST requests.

Other markers you may see

MarkerMeaning
data-pagespeed-no-defermarks a <script> to be skipped by defer_javascript
?PageSpeed=noscriptrequests the page with JavaScript-dependent rewrites (lazyload, defer) disabled — the <noscript> fallback link
mod_pagespeed_beacon / ngx_pagespeed_beaconthe URL the instrumentation beacon POSTs client-side measurements to

For the history behind content-hashed URLs, and why the rest of the web adopted the same pattern years later, see Why optimized URLs carry a content hash.

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