Troubleshooting the WHM LiteSpeed Plugin: Common Errors and Fixes

Overview

The WHM LiteSpeed plugin lets server administrators install, configure, and manage LiteSpeed Web Server (LSWS) directly from within WHM. It replaces Apache on a per-account or server-wide basis and is a popular choice for improving PHP performance and handling high traffic more efficiently than the default Apache setup.

Despite being well-maintained, the plugin has a handful of failure modes that aren’t obvious from the error messages. Licence validation failures, broken installations after cPanel updates, and cache mismatches between LiteSpeed and PHP-FPM are the most common pain points. This article covers each one with specific steps to diagnose and fix them.

If you’re running a reseller environment, these issues can affect multiple cPanel accounts at once — worth keeping in mind before you start making changes. If you’re managing accounts for clients, also check out Reseller Hosting at Host & Tech for infrastructure options built around WHM workflows.

Prerequisites

• Root SSH access to the server, or WHM root login
• cPanel/WHM version 110 or later (steps may differ on older builds)
• LiteSpeed Web Server 6.x or OpenLiteSpeed — note that the WHM plugin behaves differently for each
• A valid LiteSpeed licence (trial or purchased) — the plugin will not fully initialise without one
• Basic comfort running commands over SSH as root

Step-by-Step: Installing and Verifying the LiteSpeed Plugin

Before troubleshooting, it’s worth confirming the plugin is actually installed correctly. A partially installed plugin produces errors that look like licence or configuration problems but are really just missing files.

1. Check whether the plugin is installed. SSH into the server as root and run:
   Copied to clipboard

   /usr/local/cpanel/bin/whmapi1 get_plugins | grep -i litespeed

   If nothing returns, the plugin isn’t registered with WHM. Move to step 2. If it shows up, skip to step 3.

2. Install or reinstall the plugin. Download and run the official installer:
   Copied to clipboard

   cd /tmp
   wget -O lsws_whm_plugin.tar.gz https://www.litespeedtech.com/packages/cpanel/lsws_whm_plugin.tar.gz
   tar xzf lsws_whm_plugin.tar.gz
   cd lsws_whm_plugin
   bash install.sh

   📝 Note: Always pull the latest installer directly from LiteSpeed rather than reusing a cached copy. Plugin versions older than the current LSWS build will cause registration failures in WHM.

3. Confirm LiteSpeed is running after plugin actions.
   Copied to clipboard

   /usr/local/lsws/bin/lswsctrl status

   You should see litespeed is running with PID [number]. If it’s not running, start it:

   Copied to clipboard

   /usr/local/lsws/bin/lswsctrl start

4. Verify the licence from the command line. This is the fastest way to confirm whether a licence problem is causing plugin failures:
   Copied to clipboard

   /usr/local/lsws/bin/lshttpd -v

   The output will show the licence type and expiry. If you see License Not Found or License Expired, log into your LiteSpeed account, reissue the licence key, and re-enter it via WHM > LiteSpeed Web Server > Licence.

5. Run a post-install check via WHM. Navigate to WHM > Plugins > LiteSpeed Web Server. Click Build/Rebuild PHP to rebuild PHP with LiteSpeed SAPI. This step is skipped by a lot of people and causes PHP to continue running under Apache’s handler even after LSWS is active.

   ⚠ Warning: Rebuilding PHP will briefly restart the web server. Schedule this during a low-traffic window if possible. On a busy shared server, expect 30–90 seconds of interruption.

Common Issues and Troubleshooting

WHM Shows “LiteSpeed is Not Running” After Switching from Apache

Cause: Port 80 is still bound by Apache after the switch. LiteSpeed can’t start because the port is already in use. This happens when the switch-to-lsws script completes without fully stopping Apache first.

Fix: Stop Apache manually, confirm the port is free, then start LiteSpeed:

systemctl stop httpd
ss -tlnp | grep ':80'
/usr/local/lsws/bin/lswsctrl start

If ss still shows something on port 80 after stopping httpd, check for a stale PID file:

cat /usr/local/lsws/logs/lshttpd.pid
rm -f /usr/local/lsws/logs/lshttpd.pid
/usr/local/lsws/bin/lswsctrl start

Plugin Disappeared from WHM After a cPanel Update

Cause: cPanel updates occasionally overwrite or reset plugin registrations, especially major version jumps (e.g. 110 to 118). The LSWS files are still on disk but WHM no longer knows about them.

Fix: Re-register the plugin without a full reinstall:

cd /usr/local/lsws/admin/misc
bash plugin_update.sh

If that script doesn’t exist, run the full installer from step 2 above — it’s safe to run on top of an existing installation and won’t wipe your LSWS configuration.

📝 Note: I’d recommend adding the plugin reinstall to your post-update checklist if you’re running LSWS on a managed server. cPanel’s EasyApache 4 updates are the most common trigger for this.

“PHP Handler Not Set to LiteSpeed” Warning in WHM

Cause: PHP is still configured to use Apache’s mod_php or CGI handler. LiteSpeed has its own SAPI (Server Application Programming Interface) — if PHP wasn’t rebuilt after LSWS was installed, you lose most of LiteSpeed’s performance benefit.

Fix: In WHM, go to Software > EasyApache 4, click Customize on your current profile, and ensure the LiteSpeed SAPI package is selected for the PHP versions you’re using. Save and provision the profile. Then return to WHM > LiteSpeed Web Server and click Build PHP.

Verify it worked:

php -i | grep 'Server API'

You should see Server API => LiteSpeed. If you still see CGI/FastCGI, the rebuild didn’t complete — check /usr/local/lsws/logs/error.log for details.

LiteSpeed Cache Plugin Conflicts Causing 500 Errors on WordPress Sites

Cause: The LiteSpeed Cache WordPress plugin (LSCache) relies on server-side cache rules that need to be set at the LSWS level. If those rules aren’t in place — or if another caching plugin like WP Rocket or W3 Total Cache is active at the same time — you’ll get cache header conflicts that produce 500 errors or blank pages.

Fix: First, confirm no other caching plugin is active in WordPress. Then check whether the cache root is correctly defined in LSWS:

grep -r 'cacheRoot' /usr/local/lsws/conf/

If nothing returns, the cache root isn’t set. In WHM > LiteSpeed Web Server > Cache Manager, set the cache root to /tmp/lscache or a path on fast local storage. Restart LSWS after saving.

⚠ Warning: Don’t set the cache root to an NFS-mounted path. LiteSpeed cache writes are frequent and small — NFS latency will make this dramatically worse than no cache at all.

Licence Reverts to Trial Mode After Server Migration

Cause: LiteSpeed licences are tied to the server’s IP address. After a migration — including IP changes on Host & Tech VPS or dedicated servers — the licence validation fails silently and LSWS falls back to a 2-worker trial mode, which caps concurrent connections.

Fix: Log into your LiteSpeed account at https://store.litespeedtech.com, release the licence from the old IP, and reissue it to the new IP. Then on the server:

/usr/local/lsws/bin/lshttpd -r

This forces a licence refresh. You should see the worker count increase in the LSWS admin panel (default port 7080) under Server Status.

FAQ