How to fix CyberPanel 503 Service Unavailable (panel and websites)

A 503 Service Unavailable on a CyberPanel server means a front-end accepted the request but the thing behind it did not answer. There are two very different "things behind it", and the fix depends entirely on which one you are looking at:

• 503 on https://your-ip:8090 — the panel. OpenLiteSpeed is fine; lscpd / gunicorn (the Django app) is down or crashing.
• 503 on a website — OpenLiteSpeed or the lsphp external application for that site failed.

This guide covers both, in the order a senior admin would check them. Everything here is read-only until the section that says otherwise.

Before anything: disk, inodes, memory

Most 503s that appear "out of nowhere" have a boring cause. Check these three in ten seconds:

df -h /          # disk space
df -i /          # inodes (can be 100% with disk space left)
free -m          # RAM and swap
dmesg -T | grep -iE "out of memory|killed process" | tail

If the disk or inodes are at 100%, nothing below will work reliably and any package you reinstall may be written corrupt. Clean the disk safely first. If dmesg shows the OOM killer taking out lsphp, gunicorn or mariadbd, you have a memory problem, not a configuration problem; add swap and tune workers after you get the service back.

503 on the panel (port 8090)

1. Check the unit

systemctl status lscpd --no-pager
journalctl -xeu lscpd -n 60 --no-pager
tail -n 50 /usr/local/lscp/logs/error.log

What you see decides the fix:

Log says	Real cause	Fix
inactive (dead), no errors	Panel just is not running	systemctl enable --now lscpd
ModuleNotFoundError / ImportError: No module named psutil	Panel venv is missing a module, often after apt upgrade changed Python	See the lscpd / psutil guide
invalid ELF header, undefined symbol	A compiled module is corrupt (usually written while the disk was full)	Clean disk, then /usr/local/CyberCP/bin/pip install --force-reinstall --no-cache-dir <module>
Address already in use	Something else holds 8090, or a stale gunicorn	ss -ltnp 'sport = :8090', kill the stale process, restart
OperationalError: Can't connect to MySQL	MariaDB down; the panel cannot start without its database	systemctl restart mariadb, check its journal if it fails
status=11/SEGV	Binary or library crash	Reinstall the crashing package after a disk check

2. The transient case: a clean restart

If the journal shows no real error, do a full restart rather than a plain restart, so stale gunicorn workers and PID files do not linger:

systemctl reset-failed lscpd
pkill -9 -f "gunicorn.*CyberCP" 2>/dev/null
rm -f /usr/local/lscp/lscpd.pid
systemctl start lscpd
systemctl is-active lscpd

3. The venv case

Confirm whether the panel's own Python can import Django and psutil:

/usr/local/CyberCP/bin/python -c "import django, psutil; print('ok')"

If this fails, the fix is inside the venv, never with system pip3 (that installs to the wrong Python). Repairing one module is level 2; rebuilding the whole venv is level 3 and needs a backup of /usr/local/CyberCP/lib first. The step-by-step is in the dedicated guide.

4. The upgrade-script case

When the panel is broken by a half-finished upgrade, re-running the official upgrade script repairs the venv and files without touching your websites or databases. Take a snapshot of /usr/local/CyberCP and /usr/local/lsws/conf first and expect a few minutes of panel downtime:

sh <(curl https://raw.githubusercontent.com/usmannasir/cyberpanel/stable/preUpgrade.sh || wget -O - https://raw.githubusercontent.com/usmannasir/cyberpanel/stable/preUpgrade.sh)

503 on websites

If the panel loads but a site returns 503, OpenLiteSpeed could not get a response from the PHP backend for that site.

1. Is OpenLiteSpeed itself up?

systemctl is-active lsws
tail -n 80 /usr/local/lsws/logs/error.log

If lsws is failed, stop here and follow OpenLiteSpeed won't start.

2. Look for the PHP backend

In error.log the telling lines look like No request delivery notification has been received from LSAPI application, connection to [uds://tmp/lshttpd/lsphp.sock] failed, or Max retries exceeded. They all mean the lsphp process for that version died or could not start. Common causes:

• The site uses a PHP version that is not installed — ls /usr/local/lsws/ | grep lsphp and compare with the version set in the site's vhost or in CyberPanel.
• lsphp binary missing or broken — /usr/local/lsws/lsphp83/bin/php -v (adjust the version) must print a version.
• Memory — dmesg shows lsphp killed. Lower PHP_LSAPI_CHILDREN or add swap.
• Socket directory permissions — /tmp/lshttpd must exist and be owned by nobody (Ubuntu: nobody:nogroup, Alma: nobody:nobody).
• Disk full — lsphp cannot write session files or sockets.

3. Restart, then test the site itself

/usr/local/lsws/bin/lswsctrl restart
curl -sk -o /dev/null -w "%{http_code}\n" -H "Host: example.com" https://127.0.0.1/

A 200 or 301 means the backend answered. A 503 after the restart means one of the causes above is still present; go back to error.log, which now has a fresh entry for your request.

Verify the fix

"The command ran" is not "it is fixed". Check the effect:

systemctl is-active lscpd lsws mariadb
curl -sk -o /dev/null -w "panel %{http_code}\n" https://127.0.0.1:8090/
for d in $(ls /usr/local/lsws/conf/vhosts/); do
  printf "%-30s " "$d"; curl -sk -o /dev/null -w "%{http_code}\n" -H "Host: $d" https://127.0.0.1/
done

Every site should answer 200, 301 or 302. If one answers 500, the backend is up but the application itself is broken (PHP fatal, missing extension after an update); that is a different problem and its own guide.

What not to do

• Do not reinstall CyberPanel to fix a 503. A fresh install on a server with sites means a migration, not a fix.
• Do not rm large log files that are still open. Truncate them: truncate -s 0 /usr/local/lsws/logs/error.log.
• Do not pip3 install panel dependencies with the system Python. The panel uses /usr/local/CyberCP/bin/pip.
• Do not run a reinstall while the disk is over 95%. Clean first.