# Troubleshooting
- Installation Fails
- Update Fails
- PanelAlpha Cannot Connect to the Engine
- "This server is outdated"
- Containers Not Starting
- Containers Restart on Their Own
- Web Server Change Failed
- Site Returns 403 After a Form Submit or Upload
- Missing www on a Domain
- Wrong File Owner or Permissions
- Emails Not Sending
- Contact Support
This page covers PanelAlpha Engine 1.x, the version used with PanelAlpha Single Server and Multi Server. For Engine 2.0+, see the Troubleshooting Center.
Run the commands on this page as root on the Engine server. The paths are explained in Files, Logs and Services.
# Installation Fails
The installer prints the reason when it stops. Common messages:
| Message | What to do |
|---|---|
Please run as root! | Log in as root, or run sudo -i first. |
Unsupported operating system | Install Debian 12 or 13, or Ubuntu 22.04 or 24.04, and run the installer again. |
The license key is invalid or Invalid license status | Check the key in the client area (opens new window) and that the license is active. |
Cannot find package | The server could not download the Engine. Check that it can reach license.panelalpha.com over HTTPS. |
Also check that:
- PanelAlpha is not installed on the same server.
- No other web server, FTP server or control panel already uses ports 80, 443, 21 or 2011.
To send the output to support, run the installer with --debug and save it to a file:
bash /opt/panelalpha/engine-installer.sh --key 'YOUR_LICENSE_KEY' --debug 2>&1 | tee engine-install.log
# Update Fails
First read the logs of the last run in /opt/panelalpha/log/engine-updates/latest/ and /opt/panelalpha/log/engine-updater_<date>.log. Then:
| Message | What to do |
|---|---|
Another instance is already running. | An update is already running. Wait for it to finish. |
not compatible with background updater. Manual update required | The server is too old to update from the panel. Update from the command line as described in Update. |
Cannot detect license key or License Key is required. | Run the updater with --key 'YOUR_LICENSE_KEY'. |
The license key is invalid | Check the license in the client area, or pass another key with --key. |
Cannot detect current version | Run the updater with --force. |
If the update stopped halfway, fix the cause and run the updater again. See Recovering from a Failed Update.
# PanelAlpha Cannot Connect to the Engine
Problem: Test Connection fails, or the server shows an error in PanelAlpha.
- Check that port 2011 is open in your hosting provider's firewall and that PanelAlpha can reach it. From the PanelAlpha server, run
curl -k https://<engine-ip>:2011/api. Any HTTP response means the port is reachable. - Check the API URL in the server settings. It is the value the installer printed, for example
https://203.0.113.10:2011/api. - If you lost the API token, create a new one with
api-tokens:create(see Artisan Commands) and enter it in the server settings. - Check that the Engine containers run (see below).
# "This server is outdated"
The panel shows this message when the server runs an Engine version older than 1.0.9-beta, or when it cannot read the version at all.
- Run
system:versionon the Engine server. If the version is older than 1.0.9-beta, update from the command line as described in Update. - If the version is newer, PanelAlpha probably cannot reach the Engine. See PanelAlpha Cannot Connect to the Engine.
# Containers Not Starting
docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml ps
docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml logs --tail 200 core
df -h
- A full disk stops containers. Free space first, then run
docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml up -d. - If
webserverkeeps restarting, read its logs withlogs --tail 200 webserver. A wrong manual change in the web server configuration is a common cause.
# Containers Restart on Their Own
If you find monit_psdump_*.log files in /opt/panelalpha/log/, the server ran out of memory and monit restarted the containers that used the most. Read the newest file to see which processes used the memory. See Memory Protection.
# Web Server Change Failed
On the Details tab, hover over Change status to read the error. The full logs are in /opt/panelalpha/log/change-webserver/.
For LiteSpeed, a failed or expired trial license is a common cause. Enter your LiteSpeed serial number and try again.
# Site Returns 403 After a Form Submit or Upload
ModSecurity may be blocking the request. Check the audit log for the site's domain and the time of the request. The entry shows the ID of the rule that matched. Turn off that rule file in Loaded Config Files, or add an exclusion in Custom Rules.
To check whether ModSecurity is the cause, switch the mode to Detection Only for a moment and try again.
# Missing www on a Domain
Problem: example.com works but www.example.com does not.
docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml exec -T core php artisan users:add-missing-www-domain-aliases --all
# Wrong File Owner or Permissions
Problem: WordPress cannot write files, or a site shows permission errors after files were copied as root.
docker compose -f /opt/panelalpha/shared-hosting/docker-compose.yml exec -T core php artisan users:fix-file-permissions --username=<username>
# Emails Not Sending
See Outgoing Mail.
# Contact Support
If none of this helps, contact the Support Center (opens new window). Include the Engine version (system:version), what you did, and the relevant log files.