BugWP logo BugWP
Back to Community
Home / Community / Plugin → Litespeed cache

Troubleshooting Common LiteSpeed Cache Crawler Issues: Stuck, Stopped, and Not Running

20 threads Sep 7, 2025 Plugin → Litespeed cache

Content

Why Your LiteSpeed Cache Crawler Might Be Failing

The LiteSpeed Cache crawler is a powerful tool designed to pre-warm your page cache, ensuring visitors always get a fast, cached response. However, users often report issues where the crawler gets stuck, stops prematurely, or fails to run at all. Based on common community reports, this guide outlines the most frequent causes and their solutions.

Common Crawler Problems and Their Fixes

1. Crawler Stops or Gets Stuck Mid-Run

This is one of the most reported issues. The crawler starts but freezes at a certain position and never completes.

Why it happens: This can be caused by a server load that exceeds the set limit, a specific URL that causes a timeout, or internal corruption of the crawler's data.

How to fix it:

  • Check Server Load Limit: Navigate to LiteSpeed Cache > Crawler > Settings. If your server's current load (visible in the Crawler settings) is higher than the "Server Load Limit" value, the crawler will stop. Increase this limit or investigate what is causing high server load.
  • Reset the Crawler: Manually reset the crawler by clicking the "Reset Position" button. For a more thorough reset, you can also delete the crawler map files. Connect to your site via FTP/SFTP and remove the entire folder: /wp-content/litespeed/crawler/. Return to your WordPress admin and click "Reset Position" again.
  • Enable Debug Logging: To pinpoint the exact URL causing a hang-up, enable debug logs. Go to Toolbox > Debug Settings, set "Debug Log" to On, and in "Debug Includes" enter a keyword like crawl. Run the crawler manually. Once it stops, check Toolbox > Log View, select "Crawler Log", and look for errors. Share these logs on a pastebin site for further community assistance if needed.

2. Crawler Won't Start (Stuck on "Start watching…")

The crawler shows no activity and remains on the "Start watching…" message.

Why it happens: The most common cause is the server load being above the configured limit right from the start. It can also be due to an incorrect server IP configuration.

How to fix it:

  • Verify Server Load: As above, check if the current server load is above the limit set in the crawler settings. Temporarily increasing this limit can confirm if this is the issue.
  • Check Server IP Address: A misconfigured server IP will prevent the crawler from running. Go to LiteSpeed Cache > General > General Settings and ensure the "Server IP" field contains the correct IP address of your server. Your hosting provider can confirm this value if you are unsure.

3. All Crawler URLs Show 404 Status

The crawler runs but lists every URL with a 404 (Not Found) status, meaning it's not properly caching anything.

Why it happens: This is typically caused by a conflict with the "Drop Domain" sitemap setting.

How to fix it:

  • Navigate to LiteSpeed Cache > Crawler > Settings and ensure the option "Drop Domain from Sitemap" is disabled (unchecked).

4. Port Test Failed Error

An error message appears stating the crawler ended due to port_test_failed.

Why it happens: The plugin cannot perform a local port test, often related to an incorrect Server IP setting.

How to fix it:

  • Double-check the "Server IP" in General > General Settings. This must be your server's correct IP address.

5. Crawler Is Not Compatible With Your Server

Important Note: The LiteSpeed Cache crawler is designed specifically for LiteSpeed Web Server. If your server is running Apache + Nginx or Nginx alone, the crawler will not function correctly and should be disabled, as it provides no benefit in these environments.

When to Generate a Report

If none of the above solutions work, your next step should be to generate a detailed report for the community. You can do this by:

  1. Going to LiteSpeed Cache > Toolbox > Report.
  2. Clicking "Send to LiteSpeed".
  3. Sharing the generated Report Number (e.g., TAZDVUAA) when seeking help on community forums.

By methodically checking these common issues, you can usually get the LiteSpeed Cache crawler back on track and ensuring your site's cache remains primed for optimal performance.

Related Support Threads Support