Troubleshooting CSS/JS Issues¶
- Turn off optimization: from the WordPress Dashboard, navigate to LiteSpeed Cache > Page Optimization. Click the CSS Settings tab, and set all of the CSS optimization features to
OFF. Click the JS Settings tab, and set all of the JS optimization features to
- Purge the cache: navigate to LiteSpeed Cache > Toolbox > Purge and press the Purge All button.
- Check your site: reload the page. Does it still look bad?
If it still looks bad, then your problem is not with LSCache.
If you really don't want to do the detective work yourself you can hire LiteSpeed to do it for you.
Verify it's an Optimization Issue¶
Before we go to too much trouble, let's make sure that it really is an optimization issue. Turn off all optimization features, purge the cache, and check your site, as described at the top of this guide.
It still looks bad¶
If your site is still not displaying correctly, then the problem is not with LSCache's optimization features.
What happens if you turn of LSCache completely? Does the site look fine? If so, then some other feature of LSCache is interfering with your site. Visit our forum, and let us know what's happening.
If the site is still messed-up even after turning off LSCache, then the issue is related to something else on your site and we, unfortunately, can't help. It's probably a good time to contact your hosting provider.
It looks good now¶
This confirms that the issue lies somewhere in the optimization features. Now you have two options:
- Leave those optimization options turned off for good. This is an easy solution, and if you choose to do this, your site can still benefit greatly from caching even without optimization enabled. Remember, you don't have to use combine and minify to use LSCache!
- Turn those options back on, do some troubleshooting to find the problematic file, and exclude that file from optimization. If you want to go this route, proceed to the next step.
- Re-enable the JS-related optimization functions, and leave the CSS functions disabled.
- Purge the cache again.
- View the page. How does it look?
- If it's messy, then one of your JS files is problematic. Jump ahead to Find and Exclude.
- If it's fine, then your JS files are also fine.
- Disable the JS-related optimization functions, and re-enable the CSS functions.
- Purge the cache again.
- View the page. How does it look?
- It should be messy, indicating one of your CSS files is problematic.
Now that you know whether it's CSS or JS, you'll need to find the specific file that is causing the problem.
Find and Exclude the Problematic File(s)¶
In order to find the file that is at fault, first we need to get a list of all possible CSS (or JS) files. Once that is done, we will exclude the entire list of files from optimization, and then reintroduce them one-by-one until we've found our culprit.
Get a List¶
Using the browser's Developer Tool, visit the Network tab, and click CSS to view only the CSS files. Reload the page. You should see a list of all of the CSS files in use by that page, listed in the Name column. Exclude everything on this list from optimization. (You can exclude files by full URL or by partial path.)
If you need to see the full path of any one CSS file, click on the name of that file, and click Headers. You will find the full location of the selected file listed as Request URL.
Test the List¶
- Enable all of the optimization functions you wish to use.
- Exclude all of the CSS files from optimization: Navigate to LiteSpeed Cache > Page Optimization > Tuning Settings and enter the files from your list, one-per-line, in the CSS Excludes box.
- Purge the cache and check the site. It should be displaying correctly.
- Remove one of the CSS files from the exclude list, and purge the cache.
- Check the site.
- If it still looks ok, then that file you just removed was not the problematic file.
- If the site looks broken, then you know you have found a problematic CSS file. Put it back in the box and leave it there.
- If there are more unchecked files, repeat from Step 4.
At the end of this process your site should look good, all of the optimization functions you wish to use should be enabled, and you should have one or more problematic CSS or JS files sitting the in the CSS Excludes or JS Excludes box and eliminated from future optimization.
Don't forget, if this feels like too much trouble, we can do it for you.
CSS 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 this forum post for more details.
Critical CSS Not Loading¶
First and foremost, please make sure that all of our IP's are whitelisted on your server, your WordPress security plugins (if any), or other security apparatus on your website such as a CDN/Application Layer Firewall. You can find the IP's to be whitelisted here. If it still isn't working after that, take a look at the following:
- Check the
wp-content/litespeed/ccss/directory for any CSS files, and check if any CSS files are generated. Files should be generated inside that directory for each of the Post Types on your WordPress site.
- If the CSS files do not exist or the CCSS folder does not exist, wait for the cron to execute. The cron will generate CCSS from our Cloud Servers.
- If the CSS files exist and are valid, do a Purge All - LScache option from the Top Menu. The new CSS would not have been included in older cached pages.
- If the CSS files contain
ccss-timeout, it means communication with your server timed-out when we tried to generate Critical CSS. In this case, delete that file manually and Purge LScache so that it can re-generate.
- If the CSS files contain
Syntax Error, then one of your CSS files contains an error. You can narrow down the actual erroneous CSS file like so:
- Turn off CSS Combine and Minify
- Purge All and Purge Critical CSS
- Try to re-generate CCSS. The next CSS file generated inside
wp-content/litespeed/ccss/should show the real CSS file which has the syntax error.
- Fix the syntax error in the CSS file indicated, and Purge Critical CSS.
- Re-enable CSS Minify and CombineM/strong> again now.
Still Seeing FOUC with Critical CSS Enabled¶
Enabling the Generate Critical CSS (CCSS) feature is supposed to eliminate Flash of Unstyled Content (FOUC), so why do you sometimes still see it, even though the setting is configured to
When Load CSS Asynchronously is enabled, your site's CSS will be loaded at the same time as the HTML. So any content that is loaded before the relevant CSS will be rendered without style, as in this screenshot.
The Generate Critical CSS feature is intended to stop this behavior. It inserts essential CSS style rules inline into the page HTML, so that those rules are executed before the content loads. (You can learn more about how this works, on our blog.)
Sometimes, though, you may notice unstyled content, even when Generate Critical CSS is enabled.
FOUC happens when CCSS has not been inserted inline into the HTML of the page.
When a page renders unstyled, check the source code. You will see something similar to this:
In the image below, it's the area marked in red on line 4.
<style> tags are there, but they are empty, which means CCSS is enabled, but the rule is not yet generated/inserted into the page.
So, why wouldn't the CCSS be inserted into the page yet?
It takes a few seconds to generate Critical CSS, and if you have set Generate Critical CSS in the Background to
ON, LSCache adds the page to a cron-based queue so that the CCSS may be calculated later. As a result, there may be times when the page is loaded before the CCSS is available, and this leads to FOUC.
Please be aware that same types of pages share the same CCSS. For example, if you have post1, post2 and post3, when you access post1, CCSS will be generated. That CCSS will then be there and ready to use when post2 and post3 are accessed.
The simplest solution is to set Generate Critical CSS in the Background to
OFF. Generating CCSS in the foreground does require the first visitor to wait a few seconds, but it eliminates the FOUC problem.
Otherwise, try a Purge All - LSCache after the CCSS rules are generated. This will allow LSCache to insert CCSS into pages that had been already cached before the CCSS was generated.
When CCSS is properly inserted, you will see the rules inserted between the
<style> tags, as shown by the red line in the image below:
Debug Critical CSS Generation¶
If you have verified that CCSS has failed to generate, this may be due to a syntax error. There are a few ways to look for such errors in your CSS.
Method 1: QUIC.cloud Dashboard¶
If you have linked your site to QUIC.cloud, you can check in the QUIC.cloud dashboard. Navigate to the CCSS tab, and look for any warnings in the Recent Requests area, like so:
In this example, a CSS Syntax Error is clearly listed, along with the path to the CSS file that has the error, and a description of the error (
Unclosed block). Fix the error and CCSS should begin working properly.
Method 2: Your File System¶
If you have not linked your site to QUIC.cloud, you can directly check your file system. Navigate to the
/wp-content/litespeed/ccss directory by FTP or your control panel file manager. Look inside the CSS files in that directory. One of them should contain a syntax error.
In this example,
home.CSS gives us the
Unclosed block syntax error and tells us where to find the file to fix.
Method 3: HTML Source Code¶
Lastly, you can check the HTML source code, though this method is not as reliable as the previous two and is less preferred.
In this example, you can see the
Unclosed block error displayed in the spot where your Critical CSS should have been inserted.
Find the Original CSS File¶
Regardless of the method used, you probably discovered something like this:
/*CssSyntaxError: /wp-content/litespeed/cssjs/5aaa0.css:1:1: Unclosed block*/
/wp-content/litespeed/cssjs/5aaa0.css is the file that causes the problem, but this is not the original CSS file. Any file that you find inside of the
/wp-content/litespeed/ directory is one that has been generated by the LiteSpeed Cache plugin
In this case, it is an optimized CSS file generated through the CSS Combine and/or CSS Minify features. We cannot fix the syntax error in a generated file. We need to fix it at the source.
To find the original source CSS you will need to turn off optimization and check again.
- Navigate to Page Optimization > CSS and set CSS combine to
OFFand CSS Minify to
OFF. Save your changes.
- Navigate to Toolbox > Purge and perform a Purge All and a Purge All - CCSS, or do it from the Admin Bar as shown.
- Visit the web page so that the CCSS is regenerated.
- Use whichever method you used the first time to re-check the CCSS and look for the syntax error.
CCSS generation has a time limit to avoid server overload. If you can't get your CCSS to regenerate right away, please wait for few minutes and then try again.
Once CSS has regenerated, your error checking should reveal something like the following:
/*CssSyntaxError: /wp-includes/css/dist/block-library/style.min.css:1:1: Unclosed block*/
This is much more useful to you, as it is the original CSS file that you should be able to fix yourself. Or, at least, you should be able to contact the theme author or plugin author who provided the file to you.
If you're not sure where the CSS came from, the file name should give you a hint. If it was from a plugin, the path should look like
/wp-content/plugins/plugin-name/path/file.css. A theme's CSS should look something like
For the purpose of illustrating the issue, we deliberately sabotaged a WordPress default CSS file to trigger a syntax error. Normally,
/wp-includes/css/dist/block-library/style.min.css would not be a problematic file.
Bypass Optimization in AJAX¶
If you have a conflict, and you need to bypass optimize functions in AJAX, you can either add some code to your theme's
functions.php, or you can call the appropriate filter when using AJAX.
In the Theme's Functions¶
Add the following to your theme's
defined( 'DOING_AJAX' ) && add_filter( 'litespeed_can_optm', '__return_false' );
Call the Filter¶
When using AJAX, you can call the above filter, and return false.