Differences

This shows you the differences between two versions of the page.

--- litespeed_wiki:cache:lscwp:troubleshooting:general [2018/07/24 14:43]
Eric Leu
+++ litespeed_wiki:cache:lscwp:troubleshooting:general [2020/05/08 19:57]
Eric Leu
@@ Line 1: / Line 1: @@
-====== General Troubleshooting Guide For LSCWP ======
+====== Troubleshooting Guide For LSCWP ======
+**Please Note**: This wiki is valid for v2.9.x and below of the LiteSpeed Cache Plugin for WordPress. If you are using v3.0 or above, please see [[https://docs.litespeedtech.com/lscache/lscwp/overview/|the new documentation]].
 Here are a few common issues and how to deal with them. Please follow these steps first before logging any ticket with us since your issue might have been resolved.
+Once you've looked through this guide, if you still need help, please see [[litespeed_wiki:cache:lscwp:support|our support options]].
+===== Verify the Issue is Related to LSCache =====
+  - LSCache plugin should be activated
+  - LDCache should be enabled
+  - Navigate to **LiteSpeed Cache > Settings > Debug** and set **Disable All Features** to ''ON''
+Is the issue gone? Then the issue is probably related to LSCache.
+Are you still having a problem? Then it is //not// an LSCache issue.
 ===== Are you still using an old version of LSWCP? =====
-Our LSWCP plugin has been developed at a very fast pace. Some compatibility issue with other plugins/or break message may have already been fixed in the latest version.  You should always upgrade to the latest version and advice us which LSWCP you are using.
+Our LSWCP plugin has been 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.
-===== Image optimization problem? =====
+===== Common Issues =====
-Please check out [[litespeed_wiki:cache:lscwp:troubleshooting:image_optimize_error|image optimization guide]] first to resove your issue.
+==== LSCache Compatibility ====
-===== Logged-in Users Appearing as Logged-out/Multi site issue =====
+If a page fails to load or does not load correctly, you may have a compatibility problem. Here's how to check which feature of the plugin causes the issue:
+  - Keep LiteSpeed Cache plugin activated
+  - Set **LiteSpeed Cache > Settings > Debug > Disable All Features** to ''ON''
+  - Refresh the page see if it loads correctly
+    - If yes, 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 browser.
+    - If no, the compatibility issue is probably not related to LSCache
-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 [[litespeed_wiki:cache:common:logged-in-cookie-conflicts|Handling Logged-in Cookie Conflicts page]].
+==== CSS/JS Optimization ====
+Try the following steps to pinpoint CSS and JavaScript errors:
-===== Scheduled Posts Not Publishing On Time =====
+  - Turn off optimization. From the WordPress Dashboard, navigate to **LiteSpeed Cache > Settings > Optimize** and set all of the following to OFF: **CSSMinify**, **CSS Combine**, **CSS HTTP/2 Push**, **JS Minify**, **JS Combine**, **JS HTTP/2 Push**.
-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, which causes scheduled posts to publish late.
+  - Purge the cache. Navigate to **LiteSpeed Cache > Manage > Purge** and press the **Purge All** button.
+  - Check your site. Reload the page. Does it still look bad? If no, follow [[https://www.litespeedtech.com/support/wiki/doku.php/litespeed_wiki:cache:lscwp:optimization-troubleshooting|wiki]]
-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.
+Note: Sometimes, even when Critical CSS is enabled, the site may flash unstyled content during load. This is because the CSS file is not yet loaded due to Asynchronous loading of CSS. This is especially an issue in FireFox.
-For Example, to update scheduled posts every 15 minutes:
+==== Image Optimization ====
-<code>
+There are a few different kinds of errors that you may see when optimizing images. Take a look at [[litespeed_wiki:cache:lscwp:troubleshooting:image_optimize_error|Image Optimization Errors]].
-*/15 * * * * wget http://your_wp_site/wp-cron.php
-</code>
-When using a server level cron job, WordPress suggests defining DISABLE_WP_CRON in your wp-config file to disable checking wp-cron on a backend hit.
+==== CDN Support ====
-<code>
+You can narrow down CDN issues through the following steps:
-define('DISABLE_WP_CRON', true);
+  * Visit the CDN URL and verify that it is accessible
-</code>
+  * Check your [[litespeed_wiki:cache:lscwp:configuration:cdn|CDN settings]]
-This may be useful in reducing the number of calls made to wp-cron if that is desired.
+  * View Page Source, and verify that links are indeed pointing to the CDN URL.
-[[https://blog.litespeedtech.com/2017/05/17/wpw-using-lscache-for-wp-with-scheduled-posts/|For a more in-depth discussion of this issue, see our blog.]]
+==== 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.
-===== Some CSS Files Not Properly Reloaded After Update =====
+=== The LSCache Module is disabled at the server level ===
+This indicates that cache is turned off at the highest level. You will need to [[litespeed_wiki:cache:lscwp:installation|configure your server]], or have your hosting provider do it for you.
+=== LiteSpeed Cache is disabled in the plugin settings ===
+This indicates that you haven't turned on caching in the plugin settings. [[litespeed_wiki:cache:lscwp:configuration:general#enable_litespeed_cache|Do so]], and the problem should be solved.
+=== 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 **System Information**. The ''Server Variables'' section right at the top can give you some helpful information. Check the values of the following variables:
+  * ''LSCACHE_ADV_CACHE = true'' - 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. Simply fix by removing the ''advanced-cache.php'' file, and deactivating and reactivating the LiteSpeed Cache plugin. The file will be correctly regenerated. **NOTE:** Sometimes you do this, and the plugin still doesn't work. In this case, Navigate to **LiteSpeed Cache > Settings > Advanced** and disable **Check Advanced Cache**.
+  * ''LITESPEED_ON = true'' - If ''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. [[litespeed_wiki:cache:lscwp:installation|Learn more]].
+  * ''LITESPEED_ON_IN_SETTING = true'' - If this value is ''NULL'', navigate to the **Settings > General** page and set **Enable LiteSpeed Cache** to ''Enable''
+==== WebP Images Not Loading ====
+If you've generated WebP images through Image Optimization, but they are not showing on the front end, try these steps:
+  - Make sure you are using a browser that supports WebP. Not all of them do.
+  - Navigate to **Litespeed Cache > Settings > Media** and make sure that the **Image WebP Replacement** option is set to ''ON''.
+  - If it's on, then from **Settings > Debug**, set **Debug Log** to ''ON'' and **Debug Level** to ''Advanced''. Clear the cache, load your page, and check the debug log. Don't forget to turn the log off again when you are finished troubleshooting.
+  - If the debug log doesn't offer any explanation, try disabling and re-enabling WebP replacement. Sometimes that can fix this issue.
+==== Some CSS Files Not Properly Reloaded After Update ====
 Most likely, this is not an LSCache issue, since LSCWP doesn't cache static files.
 If your theme's CSS is not properly loaded after an update, check your browser cache. Does the reload work? Do you have a CDN or a reverse proxy in front of your webserver, such as CloudFlare? These caching mechanisms may need to be purged. See [[https://www.litespeedtech.com/support/forum/threads/wordpress-css-not-reloading.15588/#post-99620|this forum post]] for more details.
-===== Crawler Fails to Generate Sitemap File =====
+==== Forced Caching ====
-If you generate a sitemap but notice that the crawler **Size** is still ''1'' or ''2'', you can try the following steps to debug the issue.
+Sometimes, in an effort to make sure that certain pages are always cached, you erroneously force the //entire site// to be cached. Forcing this is not a good idea, because you never know when there will be individual exceptions to caching.
-{{:litespeed_wiki:cache:lscwp:troubleshooting:sitemap.png?800|}}
+Navigate to **LiteSpeed Cache > Settings > Excludes** and look in the **Force Cache URIs** box. If you see ''/'' or ''*'' there, then you will need to remove it. Save, and then Purge All LSCache.
-  - Verify that the sitemap URL works.
+==== Lazy Load ====
-  - Verify that the URLs within the sitemap are available for public visit.
+If you find some images should not be lazy loaded, you can exclude them in **LiteSpeed Cache > Settings > Media**. Add the URL to **Lazy Load Image Excludes**.
-    - If the URLs are only private, that can cause a sitemap generation issue.
-  - Verify ''/wp-content/plugins/litespeed-cache/var/crawlermap*.data'' exists.
-    - If it doesn't exist, there may be a permission issue with one of the directories in the path.
-  - Verify that the [[litespeed_wiki:cache:lscwp:environment-report|environment]] ''home_url'' is identical to the home URL in Step 2. Keep in mind that ''<nowiki>http://example.com/test.html</nowiki>'' and ''<nowiki>https://example.com/test.html</nowiki>'' are different!
-    - Fix by changing **LiteSpeed Cache > Settings > General > Site Address (URL)** to match the value in the sitemap.
+Alternately, if you are a developer, you can add the attribute ''data-no-lazy="1"'' to the image in your HTML code.
-====== How to verify LSCache compatible issue======
+==== Logged-in Users Appearing as Logged-out ====
-If page fail to load or load not correctly. You may want to check which plugin cause the issue.
-  - Keep LiteSpeed Cache plugin activate
-  - Set Debug>Disable All Features to ''ON''
-  - Refresh page see if load correctly
-    - If yes, turn on cache and functions one by one. Each time need to purge and refresh browser.
-    - If no, compatibility issue probably not relate to LSCache
+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 [[litespeed_wiki:cache:common:logged-in-cookie-conflicts|Handling Logged-in Cookie Conflicts page]].
+==== 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''
+For example:
+  "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.
+===== Advanced Issues =====
+==== 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 **Debug** settings tab, disable **Check Advanced Cache**.
+  * Verify that the cache directory (found in ''wp-content/cache'') has the proper permissions (0755)
+  * Some CDNs have cache settings that can break LSCache and cause ''X-LiteSpeed-Cache: miss'' to 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.
+==== 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. [[/litespeed_wiki:cache:lscwp:api|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 ''.htaccess'':
+  RewriteRule .* - [E=Cache-Vary:euCookie]
 ===== Provide Report Number =====
-If someday you encounter a problem that requires 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.
+If you have been through these troubleshooting steps, 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 > Report**. Press the **Send to LiteSpeed** button.  You can learn more about the Environment Report  [[litespeed_wiki:cache:lscwp:environment-report|here]].
-To generate and share your Environment Report, navigate to LiteSpeed Cache > Environment Report. Press the "Send to LiteSpeed" button.  Check [[litespeed_wiki:cache:lscwp:environment-report|here]] for details about such report.