Troubleshooting & FAQ

Symptoms, what actually causes them, and the screen or command that settles each one.

Most reports fall into one of two groups: something the stack decided and the panel is honouring, or something the server is genuinely unhappy about. The first group looks like absence; the second produces an error.

Start here

Before chasing a symptom, run the built-in checks. They cover the whole machine and name the fix for anything they catch.

cd /var/www/panel/backend
php artisan panel:doctor

The same checks are on screen under System health, where a failure carries a reference you can paste into the Error Log's Look up a reference box to read the full occurrence.

Failed blocks, warning does not

A failed check is something to fix. A warning is an optional improvement — a healthy server can carry warnings indefinitely.

Two failures that are not what they say

A clean install on a self-signed certificate reports both of these, and neither means what the message suggests:

Reported	What it actually is
Health endpoint — no response from `https://api.…/api/health`	The endpoint is fine. The check does not skip certificate verification, so a self-signed certificate fails it. Confirm with `curl -k https://api.<your-host>/api/health` — a `{"health":{"status":"ok"}}` means the only problem is the certificate. Its suggested fix mentions php-fpm, which does not exist on OpenLiteSpeed at all.
Docker — docker is installed but the daemon did not answer	Also reported when Docker is not installed, on a stack that never installs it. The probe runs `docker info` under `sudo`; where `docker` is not a permitted command the refusal is neither "not found" nor "permission denied", so it lands in the "installed but stopped" branch. Check with `command -v docker` before following its advice to start a daemon.

A screen or an option is missing

Almost always the stack, working as designed rather than failing.

"There is no Databases item in the sidebar." You are on a Docker server. Container servers manage no host database engines — an application that needs one brings it as a container. See Stack differences.

"Docker says this is not a container server." The stack is fixed at install time and there is no panel path to change it. A PHP server cannot become a container server; that needs a reinstall with --stack=docker.

"An application type is not in the create catalog." Types this server cannot serve are removed entirely rather than greyed out, so a short catalog is normal on a specialised stack. If a PHP type is missing on a PHP stack, check instead that a database engine is installed — WordPress, Joomla and friends are blocked without one, and the create screen says so at the top.

"Node.js is listed on a PHP-only server." Deliberate. Node is a build tool for PHP sites — npm ci && npm run build is the panel's own build-command placeholder — so the screen stays available even where Node sites are not served.

Creating a site fails writing its vhost

A failure that names a directory which is not there — tee: /etc/apache2/sites-available/example.test.conf: No such file or directory — means the recorded web server is not the one running.

It happens on a box that was detected rather than installed: apt remove apache2 leaves /etc/apache2 behind, so a leftover directory can out-vote the web server that is actually up.

cd /var/www/panel/backend
php artisan server:record-stack ols   # the stack this box really is

The doctor reports this mismatch by name when it cannot safely correct it itself.

OpenLiteSpeed specifics

"My .htaccess does nothing." OpenLiteSpeed only re-reads .htaccess after a restart, so the panel does not depend on it: rewrite and firewall rules are written into the site's vhconf.conf instead. WordPress is the exception — LiteSpeed Cache talks to the cache module through that file and nothing else. On any other site type, put the rule in the application's settings so the panel writes it to the vhost.

"An extension will not turn on." On OpenLiteSpeed there is nothing to turn on: every installed extension reads Always on and the list carries no toggles. Uninstall it to stop using it.

"An extension is not in the list at all." LSPHP is not PHP-FPM. Six of the usual packages — mbstring, xml, zip, gd, bcmath, soap — are compiled into the interpreter, so they are already loaded and have no package to install. Others are simply not published by LiteSpeed for your PHP version; the panel checks with apt-cache policy and skips names that cannot be installed rather than failing the whole run. An OpenLiteSpeed server offers around 21 extensions against 80 on PHP-FPM, and mongodb is one of the absentees — check the Extensions list on that server rather than assuming parity.

"A new site works on HTTP but returns 403 on HTTPS." It has no certificate yet. The panel points an un-certificated vhost at its CN=unmatched.invalid reject certificate so the site fails closed instead of answering under the panel's own certificate. Issue SSL from the application's Domains & SSL screen.

"Can the panel write a vhost for an app with no system user?" No, and on purpose. Without extUser the site's PHP would run as the web server's own nobody account, which every other site falls back to as well — one identity for the whole box, each site able to read the others' .env. The panel refuses the write instead.

Branding changes do not show up

Work down this list:

Check what the backend publishes. If this already shows your values, the backend is fine.

curl -s https://api.example.test/api/branding

If it shows the old values, the compiled config is stale:

cd /var/www/panel/backend && php artisan config:clear

If it shows the new values but the panel does not, the frontend is serving its cached copy — it re-validates only once an hour.

systemctl restart panel-frontend

If a single field is ignored while the others apply, that field failed validation and fell back: asset URLs must be absolute http(s) or root-relative, and the colour must be one the panel can parse. Full rules in Branding.

The panel is partly in English

Expected, and not a fault. Translations fall back per key, so a locale that is not fully translated shows its translated strings in that language and the rest in English — a partial language stays usable instead of failing. See Languages.

If you see a label like "Set ownership" where you expected a sentence, that is a key with no translation in any locale being rendered readably rather than as a dotted identifier.

Every page says "Something went wrong" on a brand-new install

The symptom is total: the panel never renders, so you cannot even register the administrator. Clicking past the browser's certificate warning does not help.

This happens when the installer could not get a Let's Encrypt certificate and fell back to a self-signed one. Its closing message says only that your browser will warn you, which undersells it — the failure is on the server, not in your browser. The panel's interface is a Next.js application that fetches from the API host while rendering, and Node refuses the certificate:

⨯ Error [RequestFailedError]: GET https://api.<your-host>/api/permissions failed
  [cause]: Error: self-signed certificate
    code: 'DEPTH_ZERO_SELF_SIGNED_CERT'

Confirm it with:

sudo journalctl -u panel-frontend -n 50 | grep -i cert

nip.io addresses hit this often

Let's Encrypt applies one rate limit across the whole of nip.io, which every OSS Panel test install shares. When that limit is exhausted the installer falls back, and the fallback certificate it writes carries a common name but no subjectAltName — which modern clients require, so it fails validation for the panel host and the API host alike.

The real fix is a certificate the server trusts. In order of preference:

Use your own domain. Point an A record at the server and reinstall with --domain=panel.example.com, or issue a certificate for it afterwards. This is the only option that ends with a certificate the public trusts.
Re-run certbot later, once a rate-limit slot frees up. Note that the installer's closing hint names certbot --nginx; on the OpenLiteSpeed stack nginx is not running and OpenLiteSpeed serves the vhost, so that exact command does not apply there.

Make the fallback certificate valid for both hosts, which is enough to get a test box working. Regenerate it with both names in the SAN and let Node trust it:

sudo openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
  -keyout /etc/ssl/panel/key.pem -out /etc/ssl/panel/cert.pem \
  -subj "/CN=panel.example.com" \
  -addext "subjectAltName=DNS:panel.example.com,DNS:api.example.com"
sudo cp /etc/ssl/panel/cert.pem /usr/local/share/ca-certificates/panel.crt
sudo update-ca-certificates
sudo mkdir -p /etc/systemd/system/panel-frontend.service.d
printf '[Service]\nEnvironment=NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/panel.crt\n' \
  | sudo tee /etc/systemd/system/panel-frontend.service.d/10-selfsigned-ca.conf
sudo systemctl daemon-reload && sudo systemctl restart panel-frontend

Then restart the web server. Your browser will still warn once per host — accept it on both the panel and the API address, because the interface calls the API from the page and that request gets no warning to click through, it simply fails.

The installer printed an error but finished

See Installation → Troubleshooting for the known cosmetic failure during Installing services and how to confirm the install really did complete.

Where to look when something breaks

What you want	Where
Whole-server health, with fixes	System health
A specific error, by reference	Error log
Who changed what, panel-wide	Activity log
Web server, PHP, database and system logs	System logs
One application's own logs	Application logs
A deploy that failed	Deployments
Services that should be running	Services