Back to Community
Home / Community / Plugin → Litespeed cache

Troubleshooting Common LiteSpeed Cache Image Optimization Failures

22 threads Sep 7, 2025 Plugin → Litespeed cache

Content

Why Your LiteSpeed Cache Image Optimization Gets Stuck (And How to Fix It)

One of the most powerful features of the LiteSpeed Cache plugin is its image optimization, which offloads the heavy lifting to the QUIC.cloud service. However, users frequently report that the process gets stuck, showing errors like "Image pull process failure: Failed to pull image" or that the "Pull" button remains greyed out indefinitely. Based on community reports and common solutions, this guide will help you diagnose and resolve these frustrating issues.

Why Does This Happen?

Image optimization failures are rarely due to a single cause. The process involves your WordPress site communicating with the QUIC.cloud API, which then processes and sends optimized images back to your server. A breakdown can occur at any point in this chain. Common causes include:

  • Server Configuration Issues: Certain PHP functions required for the process may be disabled on your host.
  • Connection Problems: Your server's IP might not be whitelisted with QUIC.cloud, or there could be a temporary network glitch.
  • Plugin Conflicts: Other plugins can sometimes interfere with the admin-ajax requests or the image optimization process.
  • Stuck Data in Queue: A single failed image can sometimes block the entire optimization queue from progressing.
  • QUIC.cloud Service Delays: During high traffic, the remote service may have queues, causing delays.

Step-by-Step Troubleshooting Guide

Step 1: Gather Information (The Report Number)

The first step in any troubleshooting process is to gather data. The LiteSpeed Cache plugin has a built-in reporting tool that is essential for understanding what's happening.

  1. In your WordPress admin, go to LiteSpeed Cache -> Toolbox.
  2. Click on the Report tab.
  3. Click the "Send to LiteSpeed" button.
  4. Note the 8-character uppercase Report Number (e.g., CIWGPBIH) that is generated. This number is the key to getting help in community forums, as it allows others to review your site's configuration.

Step 2: Enable Debug Logging

If the report number doesn't reveal an obvious solution, the next step is to enable detailed debug logging to see the exact error messages.

  1. Go to Toolbox -> Debug Settings.
  2. Set Debug Log to ON.
  3. Set Debug Level to Advanced.
  4. In the Debug Includes URI field, add: litespeed_type=imgoptm
  5. Save changes.
  6. Now, go to Toolbox -> Log View and click Clean Log to start fresh.
  7. Go to Image Optimization and click "Clean Up Unfinished Data".
  8. Click "Send Optimization Request" again.
  9. Wait 15-20 minutes, then check the Log View again for any new entries. These logs often contain the specific error causing the failure.

Step 3: Basic Checks and Common Fixes

Before making more complex changes, run through these common solutions:

  • Whitelist Server IPs: Ensure your origin server's IP is whitelisted in your QUIC.cloud dashboard. This is a very common cause of pull failures.
  • Check for Plugin Conflicts: Temporarily disable other plugins, especially security or login-related plugins (like WPS Hide Login), to see if the optimization process starts working.
  • Wait It Out: Sometimes the QUIC.cloud service is simply in a queue. Wait several hours to see if the process resolves itself.
  • Reset to Default Settings: A misconfiguration can sometimes cause issues. In Toolbox -> Import/Export, you can try Resetting to Default Settings to see if that resolves the problem. (Note: Export your current settings first if you wish to restore them later).

Step 4: Advanced Troubleshooting (For Persistent Issues)

For issues that refuse to go away, the community has found a few advanced workarounds. Warning: Always back up your site and database before editing core plugin files.

Potential Code Edit (Use with Caution):
Some users have reported that a specific timeout value in the plugin's code is too low for their server environment. A suggested fix is to increase this value.

  1. Access your site's files via FTP or your host's file manager.
  2. Navigate to /wp-content/plugins/litespeed-cache/src/img-optm.cls.php.
  3. Around line 1162, you may find a timeout value set to 5.6.0.
  4. Some users have had success changing this value to 8.6.0.
  5. Save the file and repeat the process of cleaning up unfinished data and sending a new request.
Important: This is a community-suggested workaround and not an official fix from the LiteSpeed Cache team. The exact line number and value may change with different plugin versions.

When All Else Fails

If you have tried all the steps above and your images still won't optimize, the best course of action is to seek help from the wider community. When you do, be sure to provide your Report Number and any relevant debug logs (you can share logs using a pastebin service). This information is critical for others to diagnose your specific server environment and configuration issue.

Persistence is key. While image optimization problems can be complex, systematically working through connection, configuration, and conflict issues will usually lead to a solution.

Related Support Threads Support