Troubleshooting

When troubleshooting, we recommend you enable LiteMage Cache only for certain IPs, such as your own admin IP. To do this, from the Magento Admin Panel, navigate to System > Configuration and in the left side menu under LITEMAGE CACHE click LiteMage Configuration. Under Developer Testing, add the desired IPs to the Enable LiteMage Cache Only for Listed IPs field.

Check These First

Many LiteMage problems can be explained by one of three issues. Please check these first:

  1. Your LiteSpeed license may not have the LiteMage module enabled. While all trial licenses include LiteMage Unlimited, the LiteMage add-on must be added to new and existing licenses. Learn how to add the Cache Module.
  2. Your Magento installation's .htaccess file may not contain the LiteMage on directive:
    <IfModule Litespeed> 
    LiteMage on 
    </IfModule>
    
  3. If you are a shared hosting account user, your host may not have enabled the LiteMage feature for your account.

LiteMage Cache Not Enabled

Your installation of LiteSpeed Web Server does not have LiteMage Cache enabled. Please make sure your LiteSpeed license includes the LiteMage cache module, and LiteMage is turned on in the .htaccess file in the root directory of your Magento installation.

If you see this error message, please check your license and .htaccess as described here.

LiteMage Option Unavailable

!

When you attempt to add LiteMage to your Magento installation, and LiteMage Cache on LiteSpeed Web Server is not appearing as a Full Page Cache option, please check your license, .htaccess, and hosting provider as described here.

LiteMage Response Header Missing

If the response header does not contain X-LiteSpeed-Cache: hit,litemage, please check your license and .htaccess as described here. If those are in order, take a look at the following possible causes.

Are you Using a LiteSpeed Server?

Check the header for litespeed, which indicates that a LiteSpeed web server is in use. LiteMage does not work with other servers, such as Apache or nginx. LiteSpeed is required.

Is the Cache Root Set?

Cache root must be set at the server level and the virtual host level. Please follow the instructions for your control panel found here

Example

In a cPanel EA4 environment, you can check the cache root with the following command:

grep -i -r lscache /etc/apache2/*
It should output the following. If it does not, then you know you will need to set them up.

/etc/apache2/conf.d/userdata/lscache_vhosts.conf:CacheRoot lscache /etc/apache2/conf.d/includes/pre_main_global.conf:CacheRoot /home/lscache/

Is Page Cache Enabled in Magento?

In System > Cache Management, refresh the Configuration and Page Cache cache types. Page Cache should be enabled, if not, then LiteMage cannot work.

!

Is the Page Cacheable?

If you've checked all of the above and still do not see the X-LiteSpeed-Cache: hit,litemage header for a particular page, it is likely that the page is non-cacheable due to a setting from another plugin.

You can verify this by switching the Magento 2 full page cache setting from LiteMage back to the built-in cache and testing the header again. Most likely you won't see a cache header there either.

To find the plugin that is causing the conflict, navigate to the /app/ and /vendor/ diretories.

Tip

Users can install modules under either /app/ or /vendor/, so both locations should be checked.

Execute the following command in each directory:

    grep -r cacheable * | grep xml | grep false
Your output might look something like the following:
    code/Mageplaza/SocialLogin/view/frontend/layout/customer_account_create.xml:        <block  class="Mageplaza\SocialLogin\Block\Popup\Authentication\Social" before="-" name="social-login-popup-authentication-social-create" ifconfig="sociallogin/general/is_enabled" template="Mageplaza_SocialLogin::form/social.phtml" cacheable="false"/>
    code/Mageplaza/SocialLogin/view/frontend/layout/customer_account_login.xml:        <block class="Mageplaza\SocialLogin\Block\Popup\Authentication\Social" after="customer.new" ifconfig="sociallogin/general/is_enabled" name="social-login-popup-authentication-social-login" template="Mageplaza_SocialLogin::form/social.phtml" cacheable="false"/>
    code/Mageplaza/SocialLogin/view/frontend/layout/default.xml:                    <block class="Mageplaza\SocialLogin\Block\Popup\Authentication\Social" name="social-login-popup-authentication-social" as="popup.authentication.social" template="popup/form/authentication/social.phtml" cacheable="false"/>
Here, cacheable="false" from default.xml will prevent Magento from caching no matter which caching method is selected. Any page containing this block will be non-cacheable. If you see that layout/default.xml contains cacheable="false", then all pages on your Magento site will be considered non-cacheable.

To fix this problem, you must disable the associated plugin or remove cacheable="false" from the default layout. Just be aware that cacheable was probably set to false for a reason, and this method may cause the associated plugin to stop functioning correctly.

default.xml controls every page, but other layout files (.xml files) may override it for different pages. In the example above, customer_account_create.xml and customer_account_login.xml are other layouts that indicate the pages controlled by them are not cacheable. Fix these layouts in the same manner as the default layout.

Tip

If you are running the Facebook Plugin, it is commonly known to make Magento stores uncacheable. It should appear in the list with the grep command above, if so.

Do You See Cache Control and Tag Headers?

When you check the header, you may see x-litespeed-cache-control and x-litespeed-tag headers but no LiteMage miss or hit:

!

Let's look at these headers more closely.

x-litespeed-cache-control:public,max-age=86400
This header indicates that the license is ok and the LiteMage plugin has been enabled. If the cache module is working and the page is cacheable, you will always see an x-litespeed-cache header, indicating either miss or hit. If you only see x-litespeed-cache-control but not x-litespeed-cache:miss, that means the cache module is not working properly.

x-litespeed-tag:cms.B_porto_homeslider_1,store,cms.B,cms_page_35,cms.B_,cms.B_Willow_custom.B_for_header,P.1207,P,P.3746,P.1229,P.3635,P.3803,P.1162,P.3582,P.3820,P.1188,P.1322,P.1223,P.1133,P.4094,P.3977,P.1153,C.2,cms.B_Willow_footer_top_1_for_1,cms.B_Willow_footer_middle_1_for_1,cms.B_Willow_footer_middle_2_for_1
The above x-litespeed-tag header should always show up together with an x-litespeed-cache:miss header. If not, it means something is wrong with the setup. The common reason is a cache root permission problem. If there is a cache root permission problem, it means the cache file cannot be written or generated correctly.

The x-litespeed-tag problem can also be caused by incorrect cache root setup, or a license restriction such as you might have with a starter plan. This can be easily viewed in Cache Management LiteMage statistics. If Cached objects is 0, then there is a cache storage issue.

Virtual host cache root is normally set to /home/$USER/lscache and it should be owned by nobody:user. If somehow you manually created this directory with user:user ownership, or you manually changed it to user:user ownership, there will be a cache module write permission issue as described above. You may also encounter this issue with some old cache files.

To fix the problem, remove the /home/$USER/lscache folder completely and restart the web server. The cache root folder (normally /home/$USER/lscache) will be created with correct ownership and permissions during the restart. Test the page again, and you should see the x-litespeed-cache:hit,litemage header.

Advanced Debugging

LiteMage 2.1.0 and above includes the X-LiteMage-Debug response headers feature, designed to make troubleshooting easier.

When you've tried everything listed above, but you still are not seeing an X-LiteSpeed-Cache: hit,litemage header, enable this debug feature to collect more information.

Navigate to Magento Admin > Stores > Advanced > LiteMage Cache > Developer Settings, and set Enable Debug to Yes and set X-LiteMage-Debug response headers. You can also add your IP to to the Log Debug Messages Only for Listed IPs field to show the debug header to your IP only.

!

Once enabled, you can browse your site, and use the browser's developer tool to check the header:

!

In this case, the Headers show:

x-litemage-debug-cc: 
x-litemage-debug-info: Layout has uncacheable blocks mgs_gdpr_login_header, wishlist-link-header, wishlist_header, wishlist_header, 
captcha-header
x-litemage-debug-tag: 
x-litemage-debug-vary:

The info Layout has uncacheable blocks mgs_gdpr_login_header, wishlist-link-header, wishlist_header, wishlist_header, captcha-header tells you that there are five blocks which are causing the page to be uncacheable. If you want to cache the page, you will either need to disable tthe blocks, or modify the template to make them cacheable.

User's First Visit Always Uncached

Some stores have plugins enabled which use cache vary cookies. A cache vary allows multiple versions of the same URL to be cached. These versions will differ from each other by currency, visitor device type, or whatever information is stored in the vary cookie.

Cache varies can be useful, but they require an additional page load for each user before a cached copy can be served. You will need to weigh the impact of this extra uncached page load against the usefulness of the plugin.

Let's look at an example to see what happens. All of these visits are from a browser in incognito mode:

With the user's first visit, the _lscache_vary cookie is set.

!

Then, in their second visit, you get the X-LiteSpeed-Cache header, and it's a miss, since this variation hasn't been cached yet.

!

Lastly, it's the third visit where a cached version of the page is finally served.

!

We can then use another browser to simulate a different user and check the same page.

With this user'd first visit, we once again see the vary cookie being set.

!

The second visit results in a cache hit, since the page has previously been cached.

!

As you can see, each new user's first visit must be uncached while the _lscache_vary cookie is being set. After the cookie is set, then the user's visit proceeds as usual, with pages hitting LiteMage Cache as either a hit or miss. If you want avoid this first uncached visit, you must locate the plugin that causes the cache vary and disable it. This may be an accessibility plugin, a currency switcher plugin, a language plugin or a geolocation plugin, among others.

If the plugin is worthwhile and you want to continue using it, that's an option, too. You could ignore this issue. It only impacts a user's first visit to one page (not the first visit to each page). For the rest of the user's visits, all pages can be served from cache, presuming they have already been cached by previous visitors.

LiteMage is Working, but Status is Blank

You can see from the X-LiteSpeed-Cache: hit,litemage header on your Magento pages that LiteMage is working properly. However, the LiteMage Cache Status section in Magento Cache Management is telling a different story. It's completely blank.

!

This is most likely caused by a server /etc/hosts file override to an incorrect Store IP addresss. This could be an IP for a staging server that you forgot to set to production. Or maybe your Admin login and the Magento store are on different servers. Your Admin server might have an override to another IP.

Take a look at the hosts file and compare it to your Magento server IP address. If they are different, there is your problem. Correct it in /etc/hosts, and that should resolve the issue. Technically, DNS should be able to locate the correct IP, and there should be no need for an override at all. Removing the line completely is the safest option.

Example

Running cat /etc/hosts reveals 185.88.259.78 yourmagentodomain.com. However, your Magento server IP is 185.88.259.80, and that is why there are no stats for your actual domain.

Additional Support

LiteMage works out of the box with Magento’s typical configuration most of the time.

As Magento allows customizations (such as to themes or plugins, etc.), sometimes these site modifications cause problems when enabling LiteMage.

LiteSpeed Technologies tries to document any issues reported and provide solutions or recommendations for such circumstances, but if the issue you are facing is not addressed in this documentation, you do have other options.

LiteSpeed Technologies offers Professional Premium Paid Support Service, provided by our LiteMage Support Engineers and LiteMage Developers, to help our clients gain the performance benefits that LiteMage can deliver.

LiteMage Support is offered in three tiers:

Tier 1 Basic

$299

Professional installation of standard LiteMage and web server / LiteMage configuration. Includes:

  • Setting up the cache root
  • Setting up the cache policy
  • Configuring LiteMage
  • Identify and Disable conflicting plugins/modules
  • Verifying that cache is working

Tier 2 Medium

$599

Professional installation of LiteMage in Magento Store with desktop/mobile detection or GeoIP detection. Includes:

  • Tier 1 Items
  • Customized rewrite rules as needed to enable LiteMage for the different views above.

Tier 3 Advanced:

1199

Professional installation of LiteMage for complex Magento stores (different customized themes, plugins, modules, etc.). Includes:

  • Tier 2 items
  • Custom xml, php or other code changes to solve the problem
  • Our experienced Magento / LiteMage developer(s) time as needed.

Worry Free Guarantee

LiteMage Premium support is fully refundable if we fail to enable LiteMage cache for your site.

How to Order

Go to the LiteSpeed store's support section. Choose LiteMage Cache Setup. Basic, the $299 option, will be shown. Click Order Now, and you will be able to select one of the 3 different tiers: Basic, Medium and Advanced. The prices in the drop-down for Medium and Advanced are in addition to the cost of Basic. Select the tier that meets your needs.


Last update: July 16, 2020