We do our best to document and provide solutions for any situation you may encounter with LiteSpeed Cache for WordPress. Please look through the topics here before logging a ticket. This guide deals mostly with caching functions. Please check the menu for troubleshooting related to site optimization features and the cache crawler.
If these guides are unable to help you, we have additional support options available.
Verify it's an LSCache Issue¶
- LSCache plugin should be activated
- LSCache should be enabled
- Navigate to LiteSpeed Cache > Toolbox > Debug Settings and set Disable All Features to
Are you still having a problem? Then it is not an LSCache issue.
Is the issue gone? Then the issue is probably related to LSCache.
To figure out which LSCache feature is at fault, turn on the cache and optimization functions one by one. Each time you turn on a new feature, you will need to Purge All and refresh the browser. When the issue comes back, you know you've found the problematic LSCache feature.
Check your LSCWP Version¶
Our LSWCP plugin is developed at a very fast pace. Some compatibility issues with other plugins may have already been fixed in the latest version. You should always upgrade to the latest version before logging a ticket.
Get a Report Number¶
If you have been through this Troubleshooting Guide, and you still require support, we may ask to see your Environment Report. The Environment Report tells us what settings you have enabled, what other plugins you have installed, and the contents of your
.htaccess file, among other useful things.
To generate and share your Environment Report, navigate to LiteSpeed Cache > Toolbox > Report, scroll down and press the Send to LiteSpeed button. Make note of the Report Number that is generated, and include it in your support request so that we may look it up on our end.
Turn On the Debug Log¶
In some situations, it may be helpful to see the WordPress debug log. Because it has the potential to take up a lot of disk space, debug logging is disabled by default. To enable it, modify
wp-config.php under WordPress' root directory as follows:
- Add the following:
debug.log file will be generated under the
wp-content directory, and will log information whenever WordPress hits the backend.
You can monitor this log during debugging using the following command:
tail -f wp-content/debug.log
Be sure to disable logging when you no longer need it.
LiteSpeed Cache is Disabled¶
If you see a warning that indicates LiteSpeed Cache is disabled, the warning itself may give a clue as to the source of the problem.
Disabled at Server Level¶
The LSCache Module is disabled at the server level
This indicates that cache is turned off at the highest level. You will need to configure your server, or have your hosting provider do it for you.
Disabled in Plugin Settings¶
LiteSpeed Cache is disabled in the plugin settings
This indicates that you haven't turned on caching in the plugin settings. Do so, and the problem should be solved.
Just Plain Disabled¶
LiteSpeed Cache is disabled
This is a generic error that doesn't indicate any cause. Navigate to LiteSpeed Cache > Toolbox > Report and look at the Report Summary. The
Server Variables section right at the top can give you some helpful information. Check the values of the following variables:
This should be
If this value is
NULL, look for the
wp-content/advanced-cache.php file which should include the line
define('LSCACHE_ADV_CACHE', true);. If the line exists, then it may be a permissions issue. Fix by removing the
advanced-cache.php file, and deactivating and reactivating the LiteSpeed Cache plugin. The file will be correctly regenerated.
Sometimes you do this, and the plugin still doesn't work. In this case, Navigate to LiteSpeed Cache > Cache > Advanced and disable Check Advanced Cache.
This should be
LSCACHE_ADV_CACHE = null, then this will always be
NULL. Otherwise, if this value is
NULL, it means that you are not running with LiteSpeed Web Server. This is allowed, but it limits the functions that you are able to use. Learn more.
This should be
If this value is
NULL, navigate to the LiteSpeed Cache > Cache page and set Enable Cache to
WordPress Lacks Permissions¶
If WordPress doesn't have access to create tables in your database, please run these SQL queries manually after installation:
CREATE TABLE IF NOT EXISTS wp_litespeed_optimizer ( id int(11) NOT NULL AUTO_INCREMENT, hash_name varchar(60) NOT NULL COMMENT “hash.filetype”, src text NOT NULL COMMENT “full url array set”, dateline int(11) NOT NULL, refer varchar(255) NOT NULL COMMENT “The container page url”, PRIMARY KEY (id), UNIQUE KEY hash_name (hash_name), KEY dateline (dateline) );
CREATE TABLE IF NOT EXISTS `wp_litespeed_img_optm` ( `id` int(11) unsigned NOT NULL AUTO_INCREMENT, `post_id` bigint(20) unsigned NOT NULL DEFAULT '0', `optm_status` varchar(64) NOT NULL DEFAULT '', `src` varchar(1000) NOT NULL DEFAULT '', `srcpath_md5` varchar(128) NOT NULL DEFAULT '', `src_md5` varchar(128) NOT NULL DEFAULT '', `server` varchar(255) NOT NULL DEFAULT '', `root_id` int(11) NOT NULL DEFAULT '0', `src_filesize` int(11) NOT NULL DEFAULT '0', `target_filesize` int(11) NOT NULL DEFAULT '0', `target_saved` int(11) NOT NULL DEFAULT '0', `webp_filesize` int(11) NOT NULL DEFAULT '0', `webp_saved` int(11) NOT NULL DEFAULT '0', PRIMARY KEY (`id`), UNIQUE KEY `post_id_2` (`post_id`,`srcpath_md5`), KEY `post_id` (`post_id`), KEY `optm_status` (`optm_status`), KEY `root_id` (`root_id`), KEY `src_md5` (`src_md5`), KEY `srcpath_md5` (`srcpath_md5`) );
If your site uses a table prefix other than
wp_, please replace the
wp_litespeed_optimizer with your site's prefix.
Sometimes, in an effort to make sure that certain pages are always cached, you erroneously force the entire site to be cached. This is not a good idea, because you never know when there will be individual exceptions to caching.
Navigate to LiteSpeed Cache > Cache > Excludes and look in the Force Cache URIs box. If you see
* there, then you will need to remove it. Save, and then Purge All LSCache.
Logged-in Users Appearing as Logged-out¶
This problem is caused when using multiple web applications under a single domain. You can find more information on this issue and how to resolve it in our Handling Logged-in Cookie Conflicts wiki.
Cache Always Misses¶
If you always see
X-LiteSpeed-Cache: miss in the headers, then something is wrong. See if any of the following steps help:
- Disable and then re-enable LSCache.
- In the LiteSpeed Cache > Cache > Advanced tab, disable Check Advanced Cache.
- Verify that the cache directory (found in
wp-content/cache) has the proper permissions (
- Some CDNs have cache settings that can break LSCache and cause
X-LiteSpeed-Cache: missto appear at all times. However, accessing the backend server directly achieves
X-LiteSpeed-Cache: hit. If this happens, turn off the CDN's cache functions.
Browser Displays Stale Content¶
Older cached versions of updated pages are being served. We've checked the response headers for the
X-LiteSpeed-Cache line, and it is not found. This indicates that the page is not coming from LiteSpeed's cache, even though it should be.
The page is being served from the browser cache due to cache rules present in
.htaccess (most likely in the WordPress root directory).
.htaccess contains an
ExpiresDefault cache rule, or an
ExpiresByType text/html cache rule that is not set to
0 seconds, the copy stored by the browser cache will be served. The page will never be requested from LiteSpeed. Because the browser cache lacks the advanced purging rules that are the backbone of LiteSpeed's accuracy, this can result in stale content being served.
If you have no other cache plugins installed, and you have no interest in using a browser cache, then you can safely remove any of the
If you want to leave the existing browser caching functionality in place, you'll need to specifically exclude the pages that are handled by LiteSpeed Cache. Add the following line above the
ExpiresByType text/html "access plus 0 seconds"
ExpiresByType text/html rule already exists, edit it so that it matches the line above.
This rule will make it so that the pages that are cached by LSCWP are not included in the browser cache, but any other browser-cache behavior will remain unchanged.
PHP Session Issues¶
Some plugins, such as WHMpress, that use PHP Session to store values (currency, language...etc) don't work with LiteSpeed Cache. Once LiteSpeed Cache is enabled, user-dependent values like currency do not work or display correctly.
Pages whose content depends on PHP Session are not cache-friendly. Once the cached page is generated, it will not vary on session data.
Why? LiteSpeed Cache is designed to avoid hitting the PHP backend. Therefore, there is no way for the cache module to know what value is stored in PHP Session for any visitor other than the first one to load the page.
To make this to work, a code change to the third party plugin is required. The developer can change the plugin to store the value in a cookie and then LiteSpeed Cache can be set to vary on that cookie.
Cache Purges Too Frequently¶
Cache is getting purged quite often, inconsistent with the TTL settings. Some actions may unintentionally trigger a purge, and it may be necessary to do some investigation to find the culprit.
- LiteSpeed Cache > Cache > Purge: Have you enabled
All pages, and you post frequently?
- LiteSpeed Cache > Cache > Purge: Have you manually added any hooks to Purge All Hooks?
- Do you have any plugins that are automatically enabled or disabled when a page loads?
All of these things will cause a Purge All action. If you can disable any of them, that should solve the problem.
Diagnosimg the Problem¶
If the cause is not obvious, you'll need to do a little digging. Enable the debug log, repeat the steps that cause a purge, disable logging, and then check the log to find the cause of any Purge All actions.
Enable LSCWP Debug Log¶
Enable the Debug Log, chosing
Admin IP only, add your IP under Admin IPs, and set Debug Level to
Reproduce the Issue¶
Execute the following steps:
- Purge All - LSCache
- Access any page twice
- Make sure the cache header is showing
- Reproduce the steps that are suspected of triggering a purge.
In this example, let's assume you have noticed unusual purging activity when you edit a WooCommerce product's inventory. The steps your would reproduce in this case are: visit home page, edit product, visit home page again.
Check the Debug Log¶
LiteSpeed Cache is a tag-based caching system, so in order to figure out what is happening, you should search for the appropriate tags in the debug log. First, we look for
X-LiteSpeed-Tag to find the pages that are impacted. We find the following lines, which correspond to home page, edit product, home page:
X-LiteSpeed-Tag: 87f1_URL.6666cd76f96956469e7be39d750cc7d9,87f1_F,87f1_Po.24,87f1_PGS,87f1_ X-LiteSpeed-Tag: 87f1_tag_priv,public:87f1_ESI,public:87f1_ESI.admin-bar,public:87f1_ X-LiteSpeed-Tag: 87f1_URL.6666cd76f96956469e7be39d750cc7d9,87f1_F,87f1_Po.24,87f1_PGS,87f1_
Then we search for
X-LiteSpeed-Purge to find the purge action. We find the following lines:
X-LiteSpeed-Purge: public,87f1_WC_T.18 X-LiteSpeed-Purge: public,87f1_WC_T.18,87f1_Po.37,87f1_URL.c5058f4b6fbb3ed974efbe319a954e61,87f1_W.recent-posts-2,87f1_T.2,87f1_T.9,87f1_T.18,87f1_A.1,87f1_PT.product,87f1_F,87f1_H,87f1_PGS,87f1_PGSRP,87f1_D.201806 X-LiteSpeed-Purge: public,87f1_WC_T.18,87f1_Po.37,87f1_URL.c5058f4b6fbb3ed974efbe319a954e61,87f1_W.recent-posts-2,87f1_T.2,87f1_T.9,87f1_T.18,87f1_A.1,87f1_PT.product,87f1_F,87f1_H,87f1_PGS,87f1_PGSRP,87f1_D.201806,87f1_REST X-LiteSpeed-Purge: public,stale,87f1_WC_T.18,87f1_Po.37,87f1_URL.c5058f4b6fbb3ed974efbe319a954e61,87f1_W.recent-posts-2,87f1_T.2,87f1_T.9,87f1_T.18,87f1_A.1,87f1_PT.product,87f1_F,87f1_H,87f1_PGS,87f1_PGSRP,87f1_D.201806,87f1_REST,87f1_WC_T.9 X-LiteSpeed-Purge: public,stale,87f1_WC_T.18,87f1_Po.37,87f1_URL.c5058f4b6fbb3ed974efbe319a954e61,87f1_W.recent-posts-2,87f1_T.2,87f1_T.9,87f1_T.18,87f1_A.1,87f1_PT.product,87f1_F,87f1_H,87f1_PGS,87f1_PGSRP,87f1_D.201806,87f1_REST,87f1_WC_T.9
Here's how it works: if the tag(s) in
X-LiteSpeed-Purge is/are contained in the
X-LiteSpeed-Tag of other pages, then those other pages will be purged during the action.
Now let's check the above tags. We will see:
87f1_PGS are contained by the homepage, so it gets purged.
87f1 is the prefix.
F stands for Front Page, and
PGS stands for Pages. You can see a full list of tag classes in the code, if you wish.
PGS are triggered by the setting Auto Purge Rules For Publish/Update. If you do not want the
Front page or
Pages to be purged every time you update a WooCommerce item, then you need to uncheck those options.
If you see the
PGSRP tag, that is for the Recent Posts Widget. You can uncheck the
all pages with Recent Posts Widget setting in the auto purge rules, to keep it from purging every page on your site. If you still want to keep the widget itself updated, enable ESI for the site, enable ESI for the Recent Posts Widget, and set it to
Public. That will keep the widget updated for new posts, but won't require every page it is on to be purged.
Page Content Not Updating Correctly¶
If your site uses a plugin that updates the content of a page without editing/saving that page, such as a "like" button that updates a counter when pressed using ajax, LSCache will not be made aware that the page should be purged from cache. As long as the now outdated copy of the page is still in cache and being served, it will appear like these changes never happened.
litespeed_purge_post($pid) API call to the offending plugin to have it notify LSCache that the page should be purged.
- Purge the cache and with the inspector open (right click page > Inspect) access the page as a guest/non-logged in user.
- In the inspector, click into the Network tab and select the page request - this is usually the first entry. With this selected, click the Header tab and check that the Response Header does not contain
- (If your plugin updates on each visit, skip this step) Refresh the page. You should now see
X-LiteSpeed-Cache: hitin your response header. This indicates that the page was served from cache.
- Trigger your plugin and make sure that the page is updated as expected.
- Refresh the page one last time.
X-LiteSpeed-Cache: hitshould once again be gone from the Response Header and the page should still contain the updated information.
A Scheduled Event has Failed¶
The following notice may appear in the Health Check plugin:
The scheduled event, litespeed_xxxx[image or ccss]_trigger, failed to run, Your site still works, but this may indicate that scheduling posts or automated updates may not work as intended
The scheduled event, litespeed_imgoptm_trigger, failed to run.
Technically, this is not a LiteSpeed issue, but is due to WordPress itself. This usually happens when WP does a version update. It will usually clear up on its own in a day or so, once the WP-Cron is back to normal.
If you don't want to wait, you can disable WP-Cron and use a 3rd party cron like cPanel cron.
Scheduled Posts Not Publishing On Time¶
Scheduled Posts are published in WordPress through a WP-Cron job. Normally, WordPress triggers the cron job each time a request hits the backend. The backend is rarely hit, however, when using a cache, and this causes scheduled posts to publish late.
LSCWP will correctly purge the cache when a scheduled post is published in the cron job. All you need to do is make sure that you can reliably hit the backend. This can be done by scheduling a cron job to hit
wp-cron.php at your ideal interval.
For Example, to update scheduled posts every 15 minutes:
*/15 * * * * wget http://your_wp_site/wp-cron.php
When using a server level cron job, WordPress suggests defining
DISABLE_WP_CRON in your
wp-config.php file to disable checking WP-Cron on a backend hit.
This may be useful in reducing the number of calls made to WP-Cron if that is desired.
For a more in-depth discussion of this issue, see our blog.
WP-Cron PHP Timing Out¶
Some WordPress plugins or operations may need to run very long PHP proceses, but they may be killed by LiteSpeed Web Server with error 500 after 120 seconds. With that in mind, we have additional environment variables that will resolve that issue.
You can use the
noconntimeout variable in the
htaccess file. Exlude WP-Cron with this rule:
<IfModule Litespeed> RewriteEngine On RewriteRule (wp-cron).php - [E=noconntimeout:1] </IfModule>
You can use the
SetEnvIf variable too, but we recommend using it only in a vhost file.
<IfModule Litespeed> SetEnv Request_URI "(wp-cron).php" noabort noconntimeout </IfModule>
For additional examples and information on how to configurate the server, you can see this wiki.
Both of these variables will allow you to run PHP processes with no limits for the web pages affected by this
Third Party Plugin Issues¶
Currency/Language Switcher Plugins¶
Because these plugins are mostly PHP session-based, there's no way to fix the caching on our end. The plugin author needs to change their code to be compatible with LSCache. See the API for more information on how to do that.
EU Cookie Consent¶
If you have EU Cookie Consent on your site, you will need a cache vary. Varying on the cookie allows two versions of each page to be stored in cache - one for people who have consented to the cookie, and one for those who have not yet done so.
Add the following line to
RewriteRule .* - [E=Cache-Vary:euCookie]
Excluding Cookie-Based Plugins From Cache¶
Some plugins, such as the YITH WooCommerce Wishlist plugin, are incompatible with LSCache for WordPress. The simplest way to avoid cache-related problems with them is to exclude their pages from cache entirely.
If a plugin is cookie-based, you need only add the plugin's specific cookie to LiteSpeed Cache's Exclude settings.
From the WordPress Dashboard, navigate to LiteSpeed Cache > Cache > Excludes. Scroll down to Do Not Cache Cookies and enter
plugin_cookie in the box. Be sure to replace "plugin_cookie" with the actual name of the plugin's cookie, as shown in the image. If you are excluding multiple cookies in this setting, make sure each cookie has its own line.
We have some known incompatible plugins on our development to-do list. We intend to fix LSCache compatibility with these plugins eventually, but for now we have set up LSCache to automatically set them to Do Not Cache.
If you are using one of these plugins, you do not have to use the manual steps above! LSCache will automatically exclude them from cache.
LSCWP provides comprehensive optimization functionality for your WordPress installation(s). With most typical WordPress installations, LSCWP works right out of the box.
However, as WordPress has many extensions/plugins/themes available, sometimes there may be conflicts. And sometimes you just want an expert to optimize the settings for you, in order to achieve the best results possible.
In the case that you need professional handling/troubleshooting of your problem, LiteSpeed Technologies offers a WordPress Cache(LSCWP) Support Service, provided by our experienced System Engineers and LSWCP Developers, to help our clients to optimize their settings or to troubleshoot conflicts. This service is for fixing single issues. We recommend you choose the Full LSCWP Tuning for Best Website Performance option for most of the time since multi-issues/tunings/tasks/steps may be involved address all of the issues and improve your metrics.
LSCWP paid support is worry free. If we find a bug, support is fully refundable!
Tier 1: Free Support¶
We provide free community support through the following areas:
- Our Troubleshooting Guide. (You're looking at it now - scroll all the way up to see available topics)
- The official WordPress plugin support forum
- Our Slack workspace, the #wpcache channel
Tier 2: LSCWP Ticket Support¶
LSCWP includes a lot of functions beyond enabling/disabling the cache feature. We can help you with troubleshooting such issues on a per task basis. This service includes but is not limited to:
- CSS/JS Optimize settings: CSS/JS Minify, CSS/JS Combine or CSS/JS HTTP2 Push. (There are restrictions. Please see NOTE 2 below.)
- Image optimization (Optimize all images for the site, convert to WebP format)
- Using LSCWP object cache with Memcached or Redis
- Crawler and other available functions in LSCWP
Please turn off CDN caching before engaging us. If a CDN cache is enabled, such as Amazon Cloud Front, or CloudFlare Cache etc, you should turn it off before we begin troubleshooting. We will be unable to ensure LSCache and the LSCache plugin are properly configured if a CDN is in the way. You can re-enable it at your own risk after we have completed our work, but we can't guarantee our cache solution will work with your CDN's cache.
NOTE 2 in regards to CSS/JS Optimization
Tier 3: LSCWP - Woocommerce Support¶
LSWCP supports the WooCommerce platform and we can help you troubleshoot problems that occur when you use LSWCP with WooCommerce.
Tier 4: Full LSCWP tuning for Best Website Performance¶
This service is a full LSCWP tuning for the best website performance/fixing multi issues. We recommend you choose this option most of the time since multiple steps may be involved to fix the issues and achieve better performance.
Tier 5: Hourly Support¶
If you have an issue that is not with the LSCWP code, but with your WordPress site's other JS/themes/plugin code, you can engage us through hourly support services.
To Order WordPress Support¶
Visit our Client Area.
Locate the following and press the Order Now button:
Under Configure > Configurable Options > Support Scope, select either
General Wordpress Site support,
Woocommerce Site support, or
Full LSCWP Tuning for Best Website Performance: