Resolving CyberPanel Blank Login Screen After MariaDB Package Upgrade

by

Root Cause Diagnosis

CyberPanel’s admin panel (CyberCP) reads and writes session, user, and two-factor data through a Django ORM that expects a specific MariaDB schema version. When the underlying MariaDB-server package is upgraded independently — through yum update, dnf update, or apt upgrade outside of CyberPanel’s own upgrade script — the server binary jumps to a newer version while the system tables (mysql.user, mysql.db, etc.) stay on the old format. This mismatch causes mariadbd to either fail to start cleanly or start in a degraded state where authentication plugins (commonly unix_socket or mysql_native_password) no longer resolve the same way CyberCP expects. The login page itself is served correctly by LiteSpeed/OpenLiteSpeed, but the backend Python process can’t complete a database handshake, so the browser receives an empty HTTP 200 response instead of a rendered login form or a visible error.

Quick Fix

Run mysql_upgrade (or mariadb-upgrade on newer builds) to force the system tables into alignment, then restart both MariaDB and the CyberPanel service:

mariadb-upgrade -u root -p
systemctl restart mariadb
systemctl restart lscpd

If the panel loads afterward, the issue was purely a stale system-table schema. If it’s still blank, proceed to the full resolution below.

Step-by-Step Resolution

1. Confirm MariaDB is actually running and reachable.

systemctl status mariadb
mysql -u root -p"$(cat /etc/cyberpanel/mysqlPassword)" -e "SELECT VERSION();"

If this fails with an authentication error rather than a connection error, the credentials file is out of sync — jump to step 4.

2. Check for a version mismatch between the running server and the client tools.

mysqladmin --version
mysql -e "SHOW VARIABLES LIKE 'version';"

A gap of more than one minor version (e.g., client on 10.3, server on 10.11) after a package manager upgrade confirms the root cause.

See also  aaPanel Nginx Reverse Proxy 502 Bad Gateway with SSL WebSocket Passthrough

3. Run the system table upgrade and check for repair actions.

mariadb-upgrade -u root -p --force

Watch the output for any OK vs error lines on mysql.user, mysql.global_priv, or mysql.db. A failed repair on global_priv is the most common culprit — MariaDB 10.4+ consolidated privilege tables into global_priv, and packages upgraded across that boundary without running the migration leave CyberCP’s queries pointing at columns that no longer exist.

4. Verify CyberPanel’s stored credentials match the live MariaDB root password.

cat /etc/cyberpanel/mysqlPassword

Compare this against what actually authenticates:

mysql -u root -p

If they differ (common when the package upgrade reset auth_socket/unix_socket as the default plugin for root), reset the password explicitly and rewrite both reference points:

ALTER USER 'root'@'localhost' IDENTIFIED BY 'your_existing_password';
FLUSH PRIVILEGES;

Then update:

  • /etc/cyberpanel/mysqlPassword
  • /usr/local/CyberCP/CyberCP/settings.py (the PASSWORD field under DATABASES)

5. Clear stale Gunicorn/CyberCP worker processes.

A blank screen often persists because the old worker processes are still holding a broken DB connection pool even after MariaDB recovers.

systemctl restart cyberpanel
systemctl restart lscpd

On installs where cyberpanel isn’t a registered service name, restart the underlying Gunicorn process manually:

ps aux | grep gunicorn
kill -9 <pid>
systemctl restart lscpd

6. Check the Django/CyberCP error log directly, since the browser gives no useful signal:

tail -n 100 /usr/local/CyberCP/error_logs/error.log

Look specifically for OperationalError, Unknown column, or Access denied entries — these map directly to steps 3 and 4 above.

7. If the schema is too far out of sync to auto-repair, dump, drop, and reimport the affected privilege tables from a known-good backup taken before the upgrade, then rerun mariadb-upgrade. Do not attempt to manually edit mysql.global_priv rows by hand; malformed JSON in that column will re-break authentication for every account, not just CyberCP’s.

See also  Fixing LiteSpeed OpenLiteSpeed Cache Crawler 403 Forbidden Loop

Why This Fails for Some Users

  • CentOS 7 / AlmaLinux 8 legacy installs: older CyberPanel builds pin MariaDB via a vendor repo (/etc/yum.repos.d/MariaDB.repo). A generic yum update can silently jump two or three minor versions at once if that repo file was left unpinned, making the schema gap too large for mariadb-upgrade to bridge in one pass — it may need to be run twice, with a restart between runs.
  • Ubuntu/Debian installs using distro-default MariaDB: apt upgrade pulls whatever version is in the distro’s repos rather than the one CyberPanel was built against, so the mismatch can happen even without the user intentionally upgrading MariaDB — a routine apt upgrade for unrelated packages triggers it as a side effect.
  • Custom auth_socket configurations: servers where root login was hardened to unix_socket authentication lose CyberCP access entirely after certain MariaDB upgrades reset the default plugin, since CyberCP always connects with a password, not a socket credential.
  • Low-memory VPS instances (512 MB–1 GB): mariadb-upgrade can be OOM-killed mid-run on constrained instances, leaving some tables upgraded and others not — check dmesg | grep -i oom if the upgrade command exits without a clear error.
  • Snapshot/restore environments: if the server was restored from a snapshot taken mid-upgrade, /etc/cyberpanel/mysqlPassword and the live MariaDB root password can diverge even though no manual password change was ever made.

Want this as a downloadable Markdown or HTML file for the site?

Leave a Comment