Troubleshooting Jetpack Boost caching issues

If you receive an error indicating that the cache isn’t working as expected, it’s essential to identify the specific problem based on the error message. Below, you’ll find detailed guidance to troubleshoot and resolve these common caching issues, ensuring your site’s caching is optimized and functional.

File access problems

Issue: Jetpack Boost’s page cache needs to update specific directories and files within your wp-content directory to function correctly. These critical locations include:

  • wp-content: The primary content directory of your WordPress installation, where Jetpack Boost tries to create a boost-cache subdirectory.
  • wp-content/boost-cache/: Contains Jetpack Boost’s page cache configuration and cached content, which must be writable.
  • wp-content/boost-cache/config.php: Holds the page cache configuration and needs to be writable.
  • wp-content/advanced-cache.php: Facilitates serving cached content before WordPress fully loads and must be writable.

Solution: Check and adjust the permissions of these files and directories to ensure they are writable by WordPress. Use FTP/SFTP to set file permissions to CHMOD 644 or 666 and directory permissions to 755 or 775. This enables Jetpack Boost to cache your site’s content effectively.

Issue: Jetpack Boost’s caching does not support the “Plain Permalinks” setting, due to its reliance on unique URLs for efficient content caching and retrieval.

Solution: Change to pretty permalinks by going to Settings → Permalinks in your WP Admin. Select any option other than “Plain” and save your changes.

Advanced cache incompatibility

Issue: Conflicts with an existing caching system, installed by another plugin or your hosting provider, can impede Jetpack Boost’s caching.

Solution:

  • Deactivate any conflicting caching plugins via the Plugins section in WP Admin.
  • For hosting-related caching conflicts, consult your provider to resolve the issue, potentially by disabling their caching solution.
  • If your hosting provider comes back to you and the issue is not resolved, check if there’s a file called advanced-cache.php in your wp-content directory. If there is one, delete it.

If you’re seeing layout issues rather than caching errors, it may be caused by a plugin conflict affecting CSS. See Potential Conflicts with Other Performance Plugins for more details.

Advanced cache for WP Super Cache

Issue: If WP Super Cache is active, it can conflict with Jetpack Boost’s caching mechanism.

Solution: Deactivate the WP Super Cache via the Plugins section in your WP Admin to eliminate the conflict and enable effective caching with Jetpack Boost.

Unable to write to advanced-cache.php

Issue: Jetpack Boost requires a writable advanced-cache.php file to efficiently serve cached content.

Solution: Adjust the advanced-cache.php permissions within the wp-content directory to CHMOD 644 or 666, ensuring Jetpack Boost can modify the file as needed.

WP_CACHE defined but not true

Issue: The WP_CACHE constant in wp-config.php must be true for Jetpack Boost to use WordPress caching capabilities. A false setting prevents activation.

Solution: Locate and modify the WP_CACHE definition in wp-config.php. Change it to true if set to false or add define( 'WP_CACHE', true ); above the "That's all, stop editing! Happy publishing." line if not defined.

WP-Config not writable

Issue: Write protection on wp-config.php can prevent Jetpack Boost from adding the necessary PHP line for caching activation.

Solution: Manually adjust wp-config.php permissions to make it writable, or add define( 'WP_CACHE', true ); manually if permissions are restricted. Ensure this line is placed above the "That's all, stop editing! Happy publishing." comment.

By identifying the specific issue based on the error message and following these solutions, you can address common problems with Jetpack Boost’s caching feature, improving your site’s performance and user experience.

Manually Deleting the Boost Cache Directory

Issue: In some cases, using the “Clear Cache” button in Jetpack Boost may not fully remove cached files from the /wp-content/boost-cache/ directory. This can lead to the accumulation of unnecessary files, contributing to high file server usage.

Solution: It is safe to manually delete the /wp-content/boost-cache/ directory if the “Clear Cache” button does not remove the files as expected. After manually deleting the folder, Jetpack Boost will regenerate the necessary cache files when it is enabled again. You can do this by accessing your site’s file manager through FTP/SFTP or your hosting provider’s control panel.

Resetting Jetpack Boost Cache After Conflicts

Issue: In some cases, Jetpack Boost’s caching feature may stop working correctly after enabling and disabling different caching plugins or making repeated changes to your site’s caching setup. If the Boost cache doesn’t activate even though it appears everything is in place, a full reset can often resolve the issue.

Solution: Follow these steps to reset the Boost cache configuration:

  1. Uninstall other caching plugins, even if they’re inactive. Do this from the Plugins page in WP Admin (don’t delete them manually via FTP). This ensures the plugins can run their cleanup routines.
  2. In the Boost settings, deactivate the Boost cache module (if it’s currently on).
  3. Delete the /wp-content/boost-cache/ folder using FTP, SFTP, or your host’s file manager.
  4. Delete the wp-content/advanced-cache.php file, if it exists.
  5. Open your wp-config.php file and look for a line like define( 'WP_CACHE', true ); — remove it or comment it out if present.

After completing these steps:

  • Reactivate the Boost cache module from the Boost settings.
  • Boost will recreate the necessary files and regenerate its cache configuration.

This reset is especially helpful if caching broke after switching between multiple plugins or hosts. If you’re unsure about any of the steps, your hosting provider may be able to help.

Get help

Need more help? Feel free to contact us! For free Jetpack Boost users, you can post a support request on the Jetpack Boost Plugin Support page. If you upgraded, you can contact support for more personalized assistance.

Comments Off on Troubleshooting Jetpack Boost caching issues

How to Test WP Super Cache

Test within WP Super Cache

This plugin has a cache tester built into the settings page. Follow these steps to test it:

  1. Go to Settings -> WP Super Cache
  2. Look for the “Cache Tester” form on the easy settings page.
  3. Click “Test Cache” and the plugin will request the front page of the site twice, comparing a timestamp on each to make sure they match.

Test WP Super Cache manually

Sometimes the tester fails, usually if the server is not configured correctly or there are strict security rules blocking those requests, and it can’t send a request to itself.

In those cases you need to test the caching manually:

  1. In the Debug settings page of the plugin make sure that “Cache Status Message” is enabled.
  2. Open a private/incognito browser window and load your website.
  3. View the source of the page and examine the timestamp at the end of the page. It should look like:
<!-- Dynamic Page Served (once) in 0.829 seconds -->
<!-- Cached page generated by WP-Super-Cache on 2009-01-12 16:11:54 -->
<!-- Compression = gzip -->
  1. Force reload the page (hold shift and click on reload) and view the source again.
  2. Confirm that the timestamp matches what you saw when you loaded the page for the first time.
  3. If timestamps do not match, then enable the debugging in the plugin. The debug log should explain why a cached page wasn’t saved or served.

Check HTTP headers

You can also check if WP Super Cache is working by looking at the HTTP headers. You’ll see that PHP-cached pages will have the header “WP-Super-Cache: Served supercache file from PHP”. WPCache cached files will have the header, “WP-Super-Cache: Served WPCache cache file”. You should also look for your cache directory in wp-content/cache/supercache/hostname/ for static cache files.

If the plugin rules are missing from your .htaccess file, the plugin will attempt to serve the super cached page if it’s found. In this case, you’ll see that the header will be “WP-Super-Cache: Served supercache file from PHP”. The pagespeed module for Apache may cause problems when testing. Disable it if you notice any problems running the cache tester.

Still need help?

Please contact support. We’re happy to advise.

Comments Off on How to Test WP Super Cache

WP Super Cache Advanced Troubleshooting Checklist

If you have trouble after activating WP Super Cache, check the following checklists and possible problems/scenarios to find a solution.

General settings for WP Super Cache

  1. Is wp-content/ writable by the web server?
  2. Try the Settings -> WP Super Cache page again and enable cache.
  3. The plugin does not work very well when PHP’s safe mode is active. This must be disabled by your administrator.
  4. Make sure cache/wp_cache_mutex.lock is writable by the web server if using coarse file locking.
  5. The cache folder cannot be put on an NFS or Samba or NAS share. It has to be on a local disk. File locking and deleting expired files will not work correctly unless the cache folder is on the local machine.
  6. After uninstalling, your permalinks may break if you remove the WordPress mod_rewrite rules too. Regenerate those rules by visiting the Settings -> Permalink page and saving that form again.
  7. If your browser asks you to save the file after installing Super Cache, you must disable Super Cache compression. Go to the Settings -> WP Super Cache page and disable it there.
  8. If certain characters do not appear correctly on your website, your server may not be configured correctly. You need to tell visitors what character set is used. Go to Settings -> Reading and copy the ‘Encoding for pages and feeds’ value. Edit the .htaccess file with all your Supercache and WordPress rewrite rules and add this at the top, replacing CHARSET with the copied value. (for example, ‘UTF-8’)
AddDefaultCharset CHARSET
  1. Your front page is okay, but posts and pages give a 404. Go to Settings -> Permalink and click “Save” after selecting a custom permalink structure. You may need to update your .htaccess file manually.
  2. If pages are randomly super cached and sometimes not, your blog can probably be viewed with and without the “www” prefix on the URL. Add this to your .htaccess above the Supercache and WordPress rules. Change example.com to your own hostname.
RewriteCond %{HTTP_HOST} www.example.com$ [NC]
RewriteRule ^(.*)$ https://example.com/$1 [L,R=301]

The latest versions redirect themselves (you should always be running the latest version of WordPress anyway!)

WP Super Cache Error messages

  1. Anything in your PHP error_log?
  2. File locking errors such as “failed to acquire key 0x152b: Permission denied in…” or “Page not cached by WP Super Cache. Could not get mutex lock.” are a sign that you may have to use file locking. Edit wp-content/wp-cache-config.php and uncomment $use_flock = true or set $sem_id to a different value. You can also disable file locking from the Admin screen as a last resort.
  3. The error message, “WP Super Cache is installed but broken. The path to wp-cache-phase1.php in wp-content/advanced-cache.php must be fixed!” appears at the end of every page. Open the file wp-content/advanced-cache.php in your favourite editor. Is the path to wp-cache-phase1.php correct? This file will normally be in wp-content/plugins/wp-super-cache/. If it is not correct the caching engine will not load.
  4. The “white screen of death” or a blank page when you visit your site is almost always caused by a PHP error, but it may also be caused by APC. If you have trouble, disable that PHP extension and replace it with eAccelerator or Xcache.
  5. The error message, “WP Super Cache is installed but broken. The constant WPCACHEHOME must be set in the file wp-config.php and point at the WP Super Cache plugin directory.” appears at the end of every page. You can delete wp-content/advanced-cache.php and reload the plugin settings page or edit wp-config.php and look for WPCACHEHOME and make sure it points at the wp-super-cache folder. This will normally be wp-content/plugins/wp-super-cache/ but you’ll likely need the full path to that file (so it’s easier to let the settings page fix it). If it is not correct the caching engine will not load.

Files and directories to check when using WP Super Cache

  1. Is there a wp-content/wp-cache-config.php ? If not, copy the file wp-super-cache/wp-cache-config-sample.php to wp-content/wp-cache-config.php and make sure WPCACHEHOME points at the right place.
  2. Is there a wp-content/advanced-cache.php ? If not, then you must copy wp-super-cache/advanced-cache.php into wp-content/. You must edit the file and change the path to point at the wp-super-cache folder.
  3. If pages are not cached at all, remove wp-content/advanced-cache.php and recreate it, following the advice above.
  4. Make sure the following line is in wp-config.php and it is ABOVE the require_once(ABSPATH.'wp-settings.php'); line:
define( 'WP_CACHE', true );
  1. Look in wp-content/cache/supercache/. Are there directories and files there?
  2. Set the variable $htaccess_path in wp-config.php or wp-cache-config.php to the path of your global .htaccess if the plugin is looking for that file in the wrong directory. This might happen if you have WordPress installed unusually.

Garbage collection issues

If you see garbage in your browser after enabling compression in the plugin, compression may already be enabled in your web server. In Apache you must disable mod_deflate, or in PHP zlib compression may be enabled. You can disable that in three ways. If you have root access, edit your php.ini and find the zlib.output_compression setting and make sure it’s “Off” or add this line to your .htaccess:

php_flag zlib.output_compression off

If that doesn’t work, add this line to your wp-config.php:

ini_set('zlib.output_compression', 0);

Garbage collection of old cache files won’t work if WordPress can’t find wp-cron.php. If your hostname resolves to 127.0.0.1, it could prevent the garbage collection from working. Check your access_logs for wp-cron.php entries. Do they return a 404 (file not found) or 200 code? If it’s 404 or you don’t see wp-cron.php anywhere, WordPress may be looking for that script in the wrong place. You should ask your server administrator to correct this or edit /etc/hosts on Unix servers and remove the following line. Your hostname must resolve to the external IP address other servers on the network/Internet use. A line like “127.0.0.1 localhost localhost.localdomain” is ok.

127.0.0.1 example.com

Use WP Crontrol to help diagnose garbage collection and preload problems. Use the plugin to make sure jobs are scheduled and for what time. Look for the wp_cache_gc and wp_cache_full_preload_hook jobs.

Miscellaneous WP Super Cache problems

  • Private Server users at Dreamhost should edit wp-content/wp-cache-config.php and set the cache dir to /tmp/ if they are getting errors about increasing CPU usage. See this discussion for more.
  • If old pages are being served to your visitors via Super Cache, you may be missing Apache modules (or their equivalents if you don’t use Apache). 3 modules are required: mod_mime, mod_headers and mod_expires. The last two are especially important for making sure browsers load new versions of existing pages on your site.
  • Caching doesn’t work. The timestamp on my blog keeps changing when I reload. Check that the path in your .htaccess rules matches where the supercache directory is. You may have to hardcode it. Try disabling supercache mode.
  • If supercache cache files are generated but not served, check the permissions on all your wp-content/cache/supercache folders (and each of wp-content cache and supercache folders) and wp-content/cache/.htaccess. If your PHP runs as a different user than Apache and permissions are strict, Apache may not be able to read the PHP-generated cache files. To fix you must add the following line to your wp-config.php (Add it above the WP_CACHE define.) Then clear your cache.
umask( 0022 );
  • If your blog refuses to load make sure your wp-config.php is correct. Are you missing an opening or closing PHP tag?
  • If your server is running into trouble because of the number of semaphores used by the plugin, it’s because your users are using file locking, which is not recommended (but is needed by a small number of users). You can globally disable file locking by defining the constant WPSC_DISABLE_LOCKING, or defining the constant WPSC_REMOVE_SEMAPHORE so that sem_remove() is called after every page is cached, but that seems to cause problems for other processes that request the same semaphore. Best to disable it.

Still need help?

Please contact support. We’re happy to advise.

Comments Off on WP Super Cache Advanced Troubleshooting Checklist

Uninstall WP Cache manually, in an emergency

WP Super Cache has to modify configuration files that WordPress uses. On rare occasions, the modifications fail, which will cause an error when the website is loaded.

If you cannot load your site to remove or deactivate WP Super Cache, you will have to edit some files so the plugin does not load. Follow these steps:

  1. Use the file manager provided by your hosting provider or an FTP tool to find the files on your host.
  2. Edit wp-config.php and delete the line that has the text WP_CACHE in it. Also, do the same with the line containing WPCACHEHOME.
  3. Edit the .htaccess file, which is probably in the same directory as the wp-config.php. You may need to “show hidden files” in your file manager to see it. Delete any lines between BEGIN WPSuperCache and END WPSuperCache.
  4. Delete the files wp-content/advanced-cache.php and wp-content/wp-cache-config.php

If you do not have the right permissions to edit the files, check your hosting provider’s documentation on how to adjust your permissions.

Still need help?

Please contact support. We’re happy to advise.

Comments Off on Uninstall WP Cache manually, in an emergency

Enable WP Cache debugging

Troubleshoot caching issues effectively by enabling the debug mode in WP Super Cache.

Enabling debug mode in WP Super Cache helps you identify and resolve caching issues more efficiently.

Activate the debug mode

You can activate the debug mode by following these steps:

  1. Navigate to your WP Admin dashboard.
  2. Select Settings → WP Super Cache.
  3. Click the Debug tab.
  4. Click the Enable Logging button.

Login to the debugging dashboard

By logging into the debugging dashboard, the system will log to a file in your cache directory. To log in follow the steps:

  1. Find the link that reads, “Login to the debugger, by clicking this link” in the WP Super Cache Settings section.
  2. Click it to be directed to the debugger’s login page, which will appear in a different browser tab.
  3. The username/password combination you will use to log in is displayed below the link you clicked on. It’s a string of characters that looks something like: d2f4429a08d7e24a25e295d410956abc (These are not the actual credentials; replace them with the one shown on your screen).
  4. Enter these credentials into the corresponding fields on the login page.

After you log in, you should see a screen that shows a log output with their timestamps.

Please note:

  • Don’t forget to deactivate the logging mode as soon as you don’t need it anymore. Logging uses server resources, which may cause issues on some servers. The logs, while password protected, still contain potentially sensitive data.
  • Do not copy and paste this log file to a public website! It contains potentially sensitive information about your web server.

Reading the Debug Log

The log file records the decisions made for each request while debug mode is active. The following examples illustrate some of the insights you can gain by reviewing the Debug Log.

Verifying if WP Super Cache is working correctly

The following code – which is similar to any code you can find in a log you generate – tells that visiting the page testington resulted in WP Super Cache serving the request:

12:46:39 90601 /2022/10/21/testington/ wp_cache_get_cookies_values: return:
12:46:39 90601 /2022/10/21/testington/ supercache dir: ABSPATH/wp-content/cache/supercache/supercache.test/2022/10/21/testington/
12:46:39 90601 /2022/10/21/testington/ wp_cache_get_cookies_values: return:
12:46:39 90601 /2022/10/21/testington/ Fetched static page data from supercache file using PHP. File: ABSPATH/wp-content/cache/supercache/supercache.test/2022/10/21/testington/index.html

2022/10/21/testington/index.html was served when the /2022/10/21/testington/ page was requested.

The index.html file is a static file, which isn’t the PHP file that WordPress usually shows. Showing the static file will be faster, which is the desired behavior.

Confirming that preloading is working

Debug Log example:

wp_cron_preload_cache: got 100 posts from position 0.
supercache dir: /home/test-user/example.com/subdir/wp-content/cache/supercache/example.com/subdir/sample-page/
wp_cron_preload_cache: fetched https://example.com/subdir/sample-page/
supercache dir: /home/test-user/example.com/subdir/wp-content/cache/supercache/example.com/subdir/2023/03/06/hello-world/
wp_cron_preload_cache: fetched https://example.com/subdir/2023/03/06/hello-world/
wpsc_delete_files: deleting /home/test-user/example.com/subdir/wp-content/cache/supercache/example.com/subdir/
wpsc_get_realpath: directory does not exist - /home/test-user/example.com/subdir/wp-content/cache/blogs/
wpsc_delete_files: reading files: ..
wpsc_delete_files: reading files: sample-page
wpsc_delete_files: reading files: 2023
wpsc_delete_files: reading files: .
wpsc_delete_files: remove directory /home/test-user/example.com/subdir/wp-content/cache/supercache/example.com/subdir/

This log was generated by setting the preload time to 0 to turn off automatic refreshing, and then click the “Preload Now” button. After a few minutes, the log generated the code shared above.

To verify that preloading is working, you will want to make sure that all the pages you expected to be preloaded are referred to in the log and that there are no lines indicating files are being deleted (note: remove directory indicates it will be removed if it is empty and is not something to be worried about).

Caching disabled for logged-in users

Debug Log example:

10:35:40 2943444 /favicon.ico wpsc_get_auth_cookies: cookies detected: wordpress_logged_in_xxxxxx
10:35:40 2943444 /favicon.ico wpsc_is_caching_user_disabled: true because logged in
10:35:40 2943444 /favicon.ico Caching disabled for logged in users on settings page.
10:35:40 2943444 /favicon.ico wp_cache_get_cookies_values: Login/postpass cookie detected

WP Super Cache isn’t caching because the user is logged in. The Debug Log flags to this on lines 2 and 3, specifically in line 3, where the logs says: Caching disabled for logged in users on settings page.

To fix this, you need to enable caching for logged-in users in WP Super Cache’s settings.

Not caching due to POST request

Debug Log example:

07:47:04 3675 /wp-admin/admin-ajax.php Not caching wp-admin requests.
07:47:09 26206 / wpsc_get_auth_cookies: no auth cookies detected
07:47:09 26206 / wpsc_is_caching_user_disabled: false
07:47:09 26206 / wp_cache_get_cookies_values: return:
07:47:09 26206 / supercache dir: ABSPATH/wp-content/cache/supercache/example.com/
07:47:09 26206 / No Super Cache file found for current URL: ABSPATH/wp-content/cache/supercache/example.com/index-https.html
07:47:09 26206 / wp_cache_get_cookies_values: return:
07:47:09 26206 / In WP Cache Phase 2
07:47:09 26206 / Setting up WordPress actions
07:47:09 26206 / Created output buffer
07:47:09 26206 / wp_cache_get_cookies_values: return:
07:47:09 26206 / wpcache_do_rebuild: doing rebuild for ABSPATH/wp-content/cache/supercache/example.com/
07:47:10 26206 / Not caching POST request.
07:47:10 26206 / wp_cache_maybe_dynamic: returned $buffer

Looking at the Debug Log, WP Super Cache isn’t caching the homepage as shown here: 07:47:10 26206 / Not caching POST request.

This is happening because another plugin or theme is populating the _POST array, leading WP Super Cache to think the page has a POST request and isn’t caching it. The solution is to check for a plugin or theme conflict.

Still need help?

If you need assistance interpreting the debug log, search the WP Super Cache forums on WordPress.org. There is likely a past thread that can help explain what you are seeing.

Alternatively, please contact support. We’re happy to advise.

Comments Off on Enable WP Cache debugging

Initial WP Super Cache Setup and Configuration

WP Super Cache generates static HTML files from your dynamic WordPress blog. After an HTML file is generated, your webserver will serve that file instead of processing the comparatively heavier and more expensive WordPress PHP scripts.

Serving static HTML files

The static HTML files will be served to the vast majority of your users:

  • Users who are not logged in.
  • Users who have not left a comment on your blog.
  • Or users who have not viewed a password-protected post.

99% of your visitors will be served static HTML files. One cached file can be served thousands of times. Other visitors will be served custom cached files tailored to their visit. If they are logged in or have left comments, those details will be displayed and cached for them.

Comments will show as soon as you moderate them, depending on the blog’s comment policy. Other dynamic elements on a page may not update unless they are written in Javascript, Java, or another client-side browser language. The plugin really produces static html pages. No PHP is executed when those pages are served.

How WP Super Cache Works

The plugin serves cached files in 3 ways (ranked by speed):

  1. Expert. The fastest method is using Apache mod_rewrite (or whatever similar module your web server supports) to serve “supercached” static HTML files. This completely bypasses PHP and is extremely quick. If your server is hit by a deluge of traffic, it is more likely to cope as the requests are “lighter”. This does require the Apache mod_rewrite module (which is probably installed if you have custom permalinks) and a modification of your .htaccess file, which is risky and may take down your site if modified incorrectly.
  2. Simple. Supercached static files can be served by PHP, the recommended way of using the plugin. The plugin will serve a “supercached” file if it exists, and it’s almost as fast as the mod_rewrite method. It’s easier to configure as the .htaccess file doesn’t need to be changed. You still need a custom permalink. You can keep portions of your page dynamic in this caching mode.
  3. WP-Cache caching. This is mainly used to cache pages for known users, URLs with parameters, and feeds. Known users are logged-in users, visitors who leave comments, or those who should be shown custom per-user data. It’s the most flexible caching method and slightly slower. WP-Cache caching will also cache visits by unknown users if supercaching is disabled. You can have dynamic parts to your page in this mode too. This mode is always enabled, but you can disable caching for known users, URLs with parameters, or feeds separately. Set the constant DISABLE_SUPERCACHE to 1 in your wp-config.php if you want only to use WP-Cache caching.

Super Cache files are compressed and stored that way so the heavy compression is done only once. These files are generally much smaller and are sent to a visitor’s browser much more quickly than uncompressed HTML. As a result, your server spends less time talking over the network which saves CPU time and bandwidth, and can also serve the next request much more quickly.

If you’re uncomfortable editing PHP files, use simple mode. It’s easy to set up and very fast.

Installing WP Super Cache

The WP Super Cache plugin can be installed from your site’s WP Admin dashboard. To install the WP Super Cache plugin via WP Admin:

  1. Go to Plugins → Add New.
  2. Search for WP Super Cache. The latest version will show in the search results.
  3. Click Install Now.
  4. Go to the plugin settings page at Settings -> WP Super Cache and enable caching.

Recommended Settings for WP Super Cache

  • Simple caching.
  • Compress pages.
  • Don’t cache pages for known users.
  • Cache rebuild.
  • CDN support.
  • Extra homepage checks.

Garbage collection is the act of cleaning up cache files that are out of date and stale. There’s no correct value for the expiry time, but a good starting point is 1800 seconds.

Consider deleting the contents of the “Rejected User Agents” text box and allow search engines to cache files for you.

Preload as many posts as you can and enable “Preload Mode”. Garbage collection of old cached files will be disabled. If you don’t care about sidebar widgets updating often set the preload interval to 2880 minutes (2 days) so all your posts aren’t recached very often. When the preload occurs, the cache files for the post being refreshed is deleted and then regenerated. Afterward, a garbage collection of all old files is performed to clean out stale cache files. Even with preload mode enabled, cached files will still be deleted when posts are modified or comments made.

Using WP Super Cache on a WordPress Multisite Network

WP Super Cache is compatible with WordPress Multisite installations (both subdomain and subdirectory configurations).

Activation in a multisite network

Network Activation is strongly recommended. Go to Network Admin → Plugins and click Network Activate.

When network-activated, WP Super Cache becomes active on every site in the network. Each subsite administrator configures caching settings independently through their own Settings → WP Super Cache panel. There is no single network-wide settings page.

Why not activate per-site?

WP Super Cache uses a global drop-in file (wp-content/advanced-cache.php) that loads on every page request across the entire network, regardless of which site activated the plugin.

Activating on just one site still affects all sites in the network and can cause unexpected behavior. Network activation ensures the plugin is properly configured everywhere it runs.

Choosing a caching mode

Simple Mode is recommended for multisite networks. It requires no .htaccess modifications and handles the routing differences between sites internally through PHP.

Expert Mode (mod_rewrite) can be used for better performance, but requires careful .htaccess configuration that varies depending on your network type:

  • Subdomain multisite (e.g., site1.example.com, site2.example.com): Expert Mode generally works reliably with the default generated rules. Each subdomain is identified by the hostname, so cache lookups are straightforward.
  • Subdirectory multisite (e.g., example.com/site1/, example.com/site2/): Expert Mode requires extra caution:
    • Rule order is critical. The WPSuperCache rewrite block in .htaccess must appear above the WordPress multisite rewrite block. If the WordPress rules are processed first, requests go to PHP before the cache can be served, defeating Expert Mode entirely.
    • Main site path overlap. The main site shares its URL root (/) with network admin paths (/wp-admin/network/). Verify the generated rewrite rules exclude admin paths.
    • Trailing slash consistency. Ensure your permalink settings enforce a consistent trailing slash. Mismatches between /site1/page and /site1/page/ cause cache misses.

Verify the plugin works

After enabling caching, test on the main site and at least two subsites:

  1. Log out (or use a private/incognito browser window).
  2. Visit a page on each site.
  3. View the page source and look for the <!-- super cache --> comment near the bottom, confirming the cached version was served.

If the comment is missing on a particular site, check that site’s WP Super Cache settings and ensure caching is enabled.

Additional Settings for WP Super Cache

Below are the main settings offered in WP Super Cache. If you need more information, you can look at the Developer documentation.

Preloading

You can generate cached files for your site’s posts, categories, and tags by preloading. Preloading will visit each page of your site, generating a cached page as it goes along, just like any other visitor to the site. Due to the sequential nature of this function, it can take some time to preload a complete site if there are many posts.

To make preloading more effective, it can be useful to disable garbage collection so that older cache files are not deleted. This is done by enabling “Preload Mode” in the settings. Be aware that pages will go out of date eventually but that updates by submitting comments or editing posts will clear portions of the cache.

Garbage Collection

Your cache directory fills up over time, which takes up space on your server. If space is limited or billed by capacity, or if you worry that the cached pages of your site will go stale, then garbage collection has to be done. Garbage collection happens regularly and deletes old files in the cache directory. On the advanced settings page, you can specify the following:

  1. Cache timeout. How long are cache files considered fresh for. After this time, they are stale and can be deleted.
  2. Scheduler. Set up how often garbage collection should be done.
  3. Notification emails. You can be informed on garbage collection job progress. There are no right or wrong settings for garbage collection. It depends on your site. If your site gets regular updates or comments, set the timeout to 1800 seconds and the timer to 600 seconds. If your site is mostly static, you can disable garbage collection by entering 0 as the timeout or use a really large timeout value.

The cache directory, usually wp-content/cache/ is only for temporary files. Do not ever put important files or symlinks to important files or directories in that directory. They will be deleted if the plugin has write access to them.

Using a CDN with WP Super Cache

A Content Delivery Network (CDN) is usually a network of computers situated around the world that will serve the content of your website faster by using servers close to you. Static files like images, Javascript, and CSS files can be served through these networks to speed up how fast your site loads. You can also create a “poor man’s CDN” by using a subdomain of your domain to serve static files too.

OSSDL CDN off-linker has been integrated into WP Super Cache to provide basic CDN support. It works by rewriting the URLs of files (excluding .php files) in wp-content and wp-includes on your server so they point at a different hostname. Many CDNs support origin pull. This means the CDN will download the file automatically from your server when it’s first requested, and will continue to serve it for a configurable length of time before downloading it again from your server.

Configure this on the “CDN” tab of the plugin settings page. This advanced technique requires a basic understanding of how your webserver or CDNs work. Please be sure to clear the file cache after you configure the CDN.

REST API

There are now REST API endpoints for accessing the settings of this plugin. You’ll need to be authenticated as an admin user with permission to view the settings page to use it. This has not been documented yet, but you can find all the code that deals with this in the “rest” directory.

Custom Caching in WP Super Cache

It is now possible to hook into the caching process using the add_cacheaction() function.

Three hooks are available:

  1. wp_cache_get_cookies_values – modify the key used by WP Cache.
  2. add_cacheaction – runs in phase2. Allows a plugin to add WordPress hooks.
  3. cache_admin_page – runs on the admin page. Use it to modify that page, perhaps by adding new configuration options.

There is one regular WordPress filter too. Use the “do_createsupercache” filter to customize the checks made before caching. The filter accepts one parameter. The output of WP-Cache’s wp_cache_get_cookies_values() function.

WP Super Cache has its own plugin system. This code is loaded when WP Super Cache loads and can be used to change how caching is done. This is before most of WordPress loads, so some functionality will not be available. Plugins can be located anywhere that PHP can load them. Add your own plugin either:

  • by putting your plugin in the wp-content/plugins/wp-super-cache-plugins directory, or
  • by calling wpsc_add_plugin( $name ) where $name is the full filename and path to the plugin. You only need to call that function once to add it. Use wpsc_delete_plugin( $name ) to remove it from the list of loaded plugins.

The cookies WP Super Cache uses to identify “known users” can be modified now by adding the names of those cookies to a list in the plugin configuration. Use wpsc_add_cookie( $name ) to add a new cookie, and wpsc_delete_cookie( $name ) to remove it. The cookie names also modify the mod_rewrite rules used by the plugin, but I recommend using Simple mode caching to avoid complications with updating the .htaccess file. The cookie name and value are used to differentiate users so that you can have one cookie but different values for each type of user on your site, for example. They’ll be served different cache files.

Still need help?

Please contact support. We’re happy to advise.

Comments Off on Initial WP Super Cache Setup and Configuration

WP Super Cache

WP Super Cache helps speed up your WordPress site by serving static HTML files instead of processing the comparatively heavier and more expensive WordPress PHP scripts. Once WP Super Cache generates the static HTML files, your web server can deliver them quicker to visitors, reduce load times and server resource usage.

Getting Started

Reporting Bugs and Requesting Features

WP Super Cache is an open-source plugin developed out of the Jetpack repository on GitHub and maintained by the Jetpack team. Let us know about any bugs and ask for enhancement/feature requests there:

In the GitHub issue template, please make sure to select “Super Cache” as the impacted plugin.

Advanced Topics

Developer Documentation

Scope of Support

If you run into issues, please try to troubleshoot by using the debug mode, or check the support forum where you can also seek help from the community. You can ask general questions about installation, standard configuration, and usage; Happiness Engineers from Jetpack are monitoring the forum and will answer your questions, we’ll do our best to point you in the right direction.

We cannot assist with:

  • Server configurations and optimizations
  • Theme-related issues: WP Super Cache is designed to be compatible with a majority of WordPress themes. However, we can’t guarantee full compatibility with every theme. In the case of theme conflicts, please work with the developers or support team of the conflicting theme.
  • Third-party plugin conflicts: We can’t ensure compatibility with other WordPress plugins. In the case of conflicts, please work with the developers or support team of the conflicting plugin.
  • Customization and custom configurations
Comments Off on WP Super Cache

Site Accelerator

Speed up your website’s loading time by optimizing your images and common static assets by serving them from our global network of servers.

Jetpack’s Site Accelerator (a.k.a. Jetpack content delivery network or CDN, formerly known as Photon) helps your pages load faster by optimizing your images and serving them alongside static files (like CSS and JavaScript) from our global network of servers.

For general features and FAQs, please see our CDN features here.

Activate Site Accelerator

Site Accelerator is deactivated by default. To activate it, please follow these steps:

  1. In your site’s dashboard, go to Jetpack → Settings → Performance.
  2. In the Performance & speed section, toggle on
Screenshot of the Performance & Speed dashboard in Jetpack.

Once you turn on Site Accelerator, please keep your photos on your server for the CDN to work correctly. We only make copies, and any images that are removed from your server will eventually “expire” and be removed from our CDN.

If you ever turn off Site Accelerator, images will continue to show on your website, they will just start loading from your webhost’s server again instead of ours. Please note that it could take a few minutes for these changes to take place.

Check that Site Accelerator is working

To check if images are loading from the CDN, you can follow these steps:

  1. Wait a few moments and then load your site in a different web browser, to avoid any caching issues.
  2. Check an image’s URL in your browser’s inspector, or open the image in its own tab. The images served from our CDN have URLs that begin https://i0.wp.comhttps://i1.wp.com, https://i2.wp.com or similar.
  3. If you do not see i0.wp.com or similar, see our troubleshooting steps below.

How Site Accelerator works

Image load times

Our Image CDN is an image optimization and editing service. We copy your photos and then host them from our servers, alleviating the load on your server and providing faster image loading for your readers.

Static file load times (Asset CDN)

The Asset CDN serves a limited set of static files only from WordPress core, Jetpack, and WooCommerce via our global network of servers. This reduces the load on your server for these specific assets.

  • It does NOT serve: static files from themes, third-party plugins, or custom scripts.
  • If you disable Site Accelerator, only WordPress core, Jetpack, and WooCommerce assets will revert to loading from your local server. Theme and plugin assets are not affected, as they were never served by Jetpack’s CDN.
  • Site accelerator filters the URLs of assets that are loaded with every WordPress page.
  • Site accelerator only acts on assets shipped with WordPress core, Jetpack, and WooCommerce.

What happens when you disable Site Accelerator?

If you turn off Site Accelerator:

  • Images will still load on your site but will no longer be served via Jetpack’s CDN.
  • WordPress core, Jetpack, and WooCommerce assets will switch back to loading from your site’s local server.
  • Theme and plugin files were never served by Site Accelerator. They will continue to load exactly as before.
  • If your site breaks after disabling Site Accelerator, check for:
    • Caching conflicts – Clear your browser and site cache (both plugins and server-side caching)
    • Missing assets – Ensure all theme and/or plugin files exist on your local server.
    • Dependencies – Some themes or plugins might expect assets to load from Jetpack’s CDN. If disabling causes problems, check with the theme or plugin developer.

Allow the Photon User Agent to Ensure Site Accelerator Works

Jetpack’s Site Accelerator (also known as the Image CDN) relies on accessing your images using a special user agent: Photon/1.0. If this user agent is blocked—by a security plugin, server rules, or firewall—Jetpack will not be able to fetch your images, and they will not be served via Site Accelerator.

Common causes of blocking:

  • Security plugins may block the Photon user agent by default.
  • Custom .htaccess rules may include blocks for unknown or bot-like user agents.
  • Firewall settings may filter or deny requests from Photon/1.0

To fix this issue:

  1. Look for .htaccess or firewall rules that may include a line like:
  2. Check any active security or optimization plugins for user agent filtering features.
  3. If present, remove it or adjust the rule to allow Photon/1.0.
  4. If you must use user agent filtering, make sure to allowlist Photon/1.0 and Jetpack requests.
  5. Optionally, allow Jetpack’s IP ranges if server-level filtering is applied.

When this is misconfigured, you may see:

  • Images not loading from i0.wp.com, i1.wp.com, etc.
  • Broken images or timeouts in the browser.
  • A 403 or empty response for requests from Jetpack servers.

Image resizing

Site Accelerator resizes photos by first checking the img element’s width and height attributes and then serving an image resized to those dimensions, or to the width of the containing element (whichever is smaller).

If there is no size set on the element, Jetpack will constrain images to the size indicated when adding the image to a post, or to your theme’s “content width” setting.

Finally, if a content width isn’t set in your theme, then Site Accelerator will default to 1,000px. This is to help ensure that sites are not trying to serve images larger than what the theme intended to be able to display.

We remove the width and height arguments to prevent your images from skewing when the resized image doesn’t have the same dimensions as the original. This is particularly important when you switch from one theme to another, and the new theme might be narrower than the previous one. One of the benefits of this is that we will automatically resize your images so they don’t exceed the width supported by your theme.

Limitations of Site Accelerator

Cache and theme/plugins

  • Site Accelerator will not fetch or process images larger than 50 MB in size.
  • Site Accelerator does not do cache invalidations. Static assets are tied to the public version of WordPress, Jetpack, or WooCommerce that you’re using. For images, if you want to “refresh” an image, you will need to change its file name. Adding random query arguments, commonly known as “cache busters,” will not work.
  • Theme and plugin assets are not supported by Site Accelerator at this time.
  • Themes and plugins can also use the Photon API to transform images using GET query arguments. Developers will find Photon API examples and documentation on developer.wordpress.com.

Self-served image purge

It is not possible to automatically purge or delete all cached site images from Jetpack servers.

If there is an image that is no longer on your server and you’d like us to remove it, please contact Jetpack support with a direct link to the file as it appears on your site. Cached image links usually begin with i0.wp.com, i1.wp.com, i2.wp.com, or i3.wp.com.

Since images can only be purged or deleted manually by individual URL, there is a limit to how many we can remove. Bulk purges or whole-site deletions for cached images are not possible.

Size edit, and type of files

  • We will not “upscale” an image in most circumstances. If your original image is 1,000px wide and you ask for Jetpack to make it 5,000px, we will serve the original 1,000px image. Upscaled images are usually of poor quality, and we want to avoid that.
  • Site Accelerator only handles GIF, PNG, JPG, and WebP images from servers that listen on port 80 for HTTP and port 443 for HTTPS. This applies to about 99.99% of the web servers in the world. If you are having issues, please try using the jetpack_photon_reject_https filter.
  • Site Accelerator does not support animated PNGs.
  • Site Accelerator does not serve audio (.mp3, .wav, .flac, etc.) or video (.mp4, .wmv, .flv, etc.) files. If you’d like to host videos on our CDN, check out our Video Hosting feature.

Server time out and serving image location

  • If your server takes longer than 10 seconds when an image is being retrieved for our CDN, the process will time out and your image will appear to be broken. Try to upload a differently-named image with a smaller dimension or file size if this happens.
  • It’s not possible to choose or limit where in the world your images will be served from. We have servers placed all over the world, and which server will load your image is dependent on a variety of factors, including the visitor’s location.

Site Accelerator is only allowed to be used by sites hosted on WordPress.com or on Jetpack-connected WordPress sites. If you move to another platform or disconnect Jetpack from your site, please also switch to another image CDN service. Any abuse of Jetpack or violation of the WordPress.com Terms of Service could result in the suspension of your site from WordPress.com-connected services, including Site Accelerator.

Troubleshooting Site Accelerator

My images don’t load

  1. Wait a few minutes and reload your site in an incognito/private browsing window. It may take time for changes to apply.
  2. Right-click an image and open it in a new tab. If the URL doesn’t start with i0.wp.com, i1.wp.com, or similar, image acceleration isn’t active.
  3. Make sure Jetpack is properly connected to WordPress.com.
  4. Some image optimization plugins may conflict with Site Accelerator by altering image URLs or introducing lazy loading mechanisms. Disable all other plugins except Jetpack and check if the issue resolves. If images display properly, re-enable plugins one by one to identify the conflicting plugin.
  5. If images still aren’t loading, switch to a default WordPress theme (e.g., Twenty Twenty-Four) to check for a theme conflict.

The static assets don’t load after disabling Asset CDN

  1. Clear your browser cache and site cache to remove any outdated references to Jetpack’s CDN.
  2. Check if the missing files exist on your local server. If they’re missing, try reinstalling WordPress core, Jetpack, or WooCommerce. If the issue persists, check for incorrect file paths or conflicts with caching plugins.
  3. If using a caching plugin, purge the cache and reload your site. Some plugins may still be referencing the old CDN URLs.
  4. Disable all other optimization plugins and test again. Some caching/minification tools may interfere with asset delivery.
  5. If issues persist, temporarily re-enable Site Accelerator and check if the problem is resolved. This helps confirm whether the issue is related to disabling the CDN.

Site Accelerator and User Agent Filters

Site Accelerator requires Jetpack to access your images using a specific user agent, Photon/1.0. If this user agent is blocked by a plugin, firewall, or server configuration, Jetpack will not be able to retrieve or cache your images. This prevents Site Accelerator from functioning correctly.

Why this matters

Jetpack’s Site Accelerator fetches and optimizes images directly from your server. This process depends on the `Photon/1.0` user agent being allowed. If it’s blocked, Jetpack cannot deliver your images via its CDN even if the feature is enabled.

Signs that the Photon user agent may be blocked

  1. Images are not loading from Jetpack CDN domains like i0.wp.com, i1.wp.com, etc.
  2. You see 403 or timeout errors in your browser’s network tools.
  3. Site Accelerator appears enabled but has no visible effect on image delivery.

How to check for and resolve user agent blocks

Check for plugin, firewall, or server rules that may be filtering or blocking user agents. Security tools like Blackhole for Bad Bots or WP-Optimize have been known to interfere with Jetpack in this way.

To verify, look for code similar to the following in your .htaccess file:

# Block Photon

RewriteEngine On
RewriteCond %{HTTP_USER_AGENT} Photon/1.0 [NC]
RewriteRule .* - [F,L]

If this rule is present, Site Accelerator will not be able to access your images. You’ll need to remove or modify the rule to allow the Photon/1.0 user agent.

If you use stricter user agent filtering, we recommend allowlisting Photon/1.0 and optionally Jetpack’s IP ranges to avoid unintended blocking.

We provide this example for reference only. Per our Scope of Support, we cannot assist with implementing or troubleshooting custom server rules.

Still need help?

Please contact support. We’re happy to advise.

Privacy Information

Site Accelerator is deactivated by default. You can toggle the feature on or off under the Performance & speed section from Jetpack → Settings → Performance in your dashboard.

Data Used
Site Owners / Users

While not actively used in the delivery of this functionality, EXIF data may exist (and be accessible to site visitors) in any of the images that you upload to your site.Additionally, for activity tracking (detailed below): IP address, WordPress.com user ID, WordPress.com username, WordPress.com-connected site ID and URL, Jetpack version, user agent, visiting URL, referring URL, timestamp of event, browser language, country code.

Site Visitors

None.

Activity Tracked
Site Owners / Users

We track when, and by which user, the feature is activated and deactivated.

Site Visitors

None.

Data Synced (Read More)
Site Owners / Users

We sync a single option that identifies whether or not the feature is activated.

Site Visitors

None.

Comments Off on Site Accelerator

Improve your site’s performance with Jetpack

Jetpack includes powerful tools to help your WordPress site load faster, perform better in search engines, and deliver a smoother experience for your visitors. Whether you’re optimizing Core Web Vitals, speeding up image load times, or reducing server load, Jetpack can help boost your site’s performance.

This guide highlights Jetpack’s most important performance tools — from built-in settings to optional plugins — to help you improve your site’s speed, stability, and SEO.

Jetpack Boost: optimize core web vitals and load speed

Jetpack Boost is a performance plugin designed to improve how quickly your site loads and help you meet Core Web Vitals — key speed metrics used by Google.

Why use it:

  • Speed up the appearance of visible content
  • Improve Largest Contentful Paint (LCP)
  • Prioritize performance on your most important pages

Includes:

  • Critical CSS: Prioritizes styling for content that loads first.
  • Defer JavaScript: Delays non-essential scripts to reduce loading time.
  • Caching: Speeds up repeat visits by saving full page versions. 
  • LCP Image Optimization: Detects and optimizes the most important image on each page.
  • Cornerstone Pages: Focuses performance improvements on specific high-value pages.

Learn more in the full Jetpack Boost guide

Performance & Speed: load assets from a global CDN

The Site Accelerator feature helps your site load faster by serving your images and static files from Jetpack’s global content delivery network (CDN).

Why use it:

  • Reduces load on your server
  • Speeds up image-heavy pages
  • Improves loading times by serving files from data centers near your visitors

You can choose to accelerate image delivery, static file delivery, or both. These options are available in the Jetpack plugin under the Performance tab at Jetpack → Settings

More about Site Accelerator

Media: fast, reliable video hosting with VideoPress

VideoPress lets you upload high-quality videos directly in the WordPress editor and delivers them quickly through Jetpack’s fast, ad-free player.

Why use it:

  • Offloads large files from your web server
  • Streams videos from a global infrastructure so videos load faster
  • Supports adaptive quality for smooth playback

More about VideoPress

Search: help visitors find content faster

Jetpack Search improves the default WordPress search with fast, real-time results and advanced filtering.

Why use it:

  • Offloads database intensive WordPress searches to cloud servers
  • Adds filters for categories, tags, dates, and more
  • Scales well for large sites and WooCommerce stores
  • Makes search feel modern and responsive

More about Jetpack Search

Caching: speed up repeat visits

Jetpack Boost includes a built-in page caching feature that stores and serves full versions of your pages for logged-out visitors. This helps reduce server load and significantly improves load times on repeat visits.

Why use it:

  • Faster page load times for returning users
  • Reduced server and database usage
  • Automatically clears cache when content is updated

Jetpack Boost’s caching works out of the box for most sites. You can also customize it with filters, adjust cache duration, exclude certain pages from caching, or enable logging for debugging.

Learn more about caching with Jetpack Boost

If you need advanced caching features or your hosting provider prevents Boost’s cache from activating, you can use WP Super Cache for more control.

More about WP Super Cache

WP Super Cache: advanced page caching

WP Super Cache is a free plugin by Automattic that saves static versions of your pages and serves them to visitors without repeated database queries.

Why use it:

  • Reduces load on high-traffic or dynamic sites
  • Improves load speed for returning visitors
  • Offers advanced configuration beyond what’s built into Jetpack Boost

View WP Super Cache setup guide

Also helpful for site stability and performance

Jetpack includes features that indirectly support speed and reliability:

  • Jetpack Protect: Blocks brute-force login attempts and bots that can slow down your site.
  • Jetpack Monitor: Alerts you if your site goes offline so you can act fast.
  • Jetpack Stats: Gives you lightweight analytics without slowing down your site.

Summary: Which tools should I use?

GoalRecommended Tool
Improve Core Web VitalsJetpack Boost
Speed up images and static filesSite Accelerator
Optimize Largest Contentful PaintJetpack Boost 
Cache full pagesJetpack Boost or WP Super Cache
Host fast, ad-free videosJetpack VideoPress
Improve content discoverabilityJetpack Search
Block malicious trafficJetpack Protect
Monitor downtimeJetpack Monitor
Lightweight visitor analyticsJetpack Stats

Need help?

Not sure which tools are right for your site? Contact Jetpack Support — we’re happy to help.

Comments Off on Improve your site’s performance with Jetpack

Lazy Loading Images

Still need help?

Please contact support. We’re happy to advise.

Privacy Information

Lazy loading has been deprecated.

Comments Off on Lazy Loading Images
  • Enter your email address to receive news and updates from Jetpack

  • Join 99.1K other subscribers
  • Browse by Topic