Back to Community
Home / Community / Plugin → Litespeed cache

Troubleshooting Common LiteSpeed Cache CSS Optimization Issues: UCSS, Async, and More

15 threads Sep 7, 2025 Plugin → Litespeed cache

Content

LiteSpeed Cache is a powerful optimization plugin, but its advanced CSS features like UCSS and Asynchronous Loading can sometimes lead to unexpected styling issues on your WordPress site. Based on community discussions, this guide covers the most common problems and their solutions.

1. Inline CSS Removed by UCSS Generation

Problem: UCSS (Unused CSS) generation can strip out inline CSS styles (e.g., <span style="background:#ffffff !important">) that lack a specific selector, breaking elements like color swatches.

Solution: Add the specific CSS property to the exclusion lists. Navigate to LiteSpeed Cache > Page Optimization > Tuning > CSS. In the UCSS File Excludes and Inline and CSS Excludes fields, enter the property (e.g., background:#ffffff). Note that wildcards like background:* are not supported. Purge UCSS afterward to regenerate.

2. Unexpected Styles in Guest Mode or with UCSS/CCSS

Problem: Unwanted styles appear when browsing as a guest or when UCSS/CCSS is active, but disappear when these optimizations are disabled. The source of these styles can be hard to trace.

Solution: This often indicates a conflict with dynamically generated CSS. First, try excluding large sections via the UCSS File Excludes and Inline field. If excluding wp-content fixes it, gradually narrow down the exclusion to a specific plugin or theme folder. If the issue persists, generate a report from Toolbox > Report for deeper analysis.

3. Lazy-Load Fade-In CSS Conflicts with UCSS

Problem: Recommended fade-in CSS for lazy-loaded images can conflict with UCSS, causing some images to never display. The problem may not appear immediately, as it only manifests after UCSS has been generated.

Solution: Add the necessary selector to the UCSS Allow List. For the recommended fade-in effect, ensure img.litespeed-loaded is added to the UCSS Allow List (found under Page Optimization > Tuning > CSS). This ensures the required CSS for the animation is always included.

4. CSS Async (Critical CSS) Loading in Header

Problem: When "Load CSS Asynchronously" is enabled, the critical CSS is loaded inline in the <head> section, not the footer.

Explanation: This is by design. The Critical CSS, which contains only the styles needed for the initial viewport, is inlined in the header to ensure the page renders correctly and quickly. Loading all CSS in the footer would delay rendering, while inlining everything would create large HTML files and reduce caching efficiency.

5. Manually Preventing Optimization of Inline CSS

Problem: Inline CSS generated by PHP is being optimized or removed even when you want to exclude it.

Solution: To prevent a specific block of inline CSS from being optimized, add the data-no-optimize="1" attribute to the <style> tag. For example: <style data-no-optimize="1">.

6. Changing the Position of Merged/Critical CSS in <head>

Problem: Merged CSS and Critical CSS files are placed very early in the <head>, before important tags like <title> and <meta>, which can be a suboptimal SEO practice.

Solution: You can force this output to appear just before the closing </head> tag by adding the following filter to your theme's functions.php file:
add_filter('litespeed_optm_html_after_head','__return_true');

General Troubleshooting Tips

  • Purge and Regenerate: After making any change to CSS optimization settings, always purge all caches (especially UCSS/CCSS) to force regeneration.
  • Use Excludes: The UCSS File Excludes and Inline field is a powerful tool for handling problematic CSS. Use it to exclude entire files or force specific CSS to be inlined.
  • Report Tool: For complex issues that are hard to diagnose, generate a report from LiteSpeed Cache > Toolbox > Report. The report number can be used for further investigation.

By understanding these common scenarios, you can effectively troubleshoot and harness the full power of LiteSpeed Cache's CSS optimization features without breaking your site's design.

Related Support Threads Support