Troubleshooting

Installation Issues

Installer fails with "dpkg lock" error

Another apt process is running (often unattended-upgrades). Wait and re-run the installer:

systemctl stop unattended-upgrades
bash <(curl -sSL https://hstpanel.net/install.sh)

The installer automatically waits for dpkg locks and retries — but stopping unattended-upgrades first avoids the wait.

Package download fails / network error

Check outbound internet access from the server:

curl -I https://hstpanel.net
ping 8.8.8.8

If the server can't reach the internet, check your hosting provider's security group or firewall rules for outbound HTTP/HTTPS.

Apache fails to start — port conflict

Another service is using port 8090 or 80. Find it:

ss -tlnp | grep -E ':80|:8090'

Stop the conflicting service, then restart Apache:

systemctl restart apache2

MariaDB won't start

Check the MariaDB error log:

journalctl -u mariadb --no-pager -n 50

Common cause: disk full. Check disk usage:

df -h

Installer completes but panel won't load

Check that nginx is running and PM2 is serving the API:

systemctl status nginx
pm2 list
pm2 logs hstpanel --lines 30

If PM2 shows the process is errored, restart it:

pm2 restart hstpanel
pm2 logs hstpanel --lines 30

Panel Access Issues

Can't reach the panel on port 8443

Check three things in order:

1. UFW is allowing port 8443: ufw status | grep 8443 — if missing, run ufw allow 8443/tcp
2. Host firewall / security group: Your hosting provider may have a separate firewall (IONOS, DigitalOcean, etc.) — check their control panel and open port 8443 there too.
3. nginx is listening: ss -tlnp | grep 8443 — if nothing shows, restart nginx: systemctl restart nginx

Panel loads but shows a blank page

The API server may not be running. Check:

pm2 list
curl -s http://127.0.0.1:8090/api/health

If the health check fails, restart the API:

pm2 restart hstpanel

Browser shows "NET::ERR_CERT_INVALID"

This is expected for self-signed certificates. Click Advanced → Proceed to [IP] (unsafe). To get a trusted certificate, point a domain to your server and issue a Let's Encrypt cert from WHM → SSL.

Locked out — forgot root password

If you've lost SSH access, use your hosting provider's VNC/console access (IONOS: Server → Console, DigitalOcean: Droplet → Console) to reset the root password.

Email Issues

Emails not being delivered outbound

Many hosting providers block port 25 by default. Check:

nc -zv smtp.gmail.com 25

If blocked, contact your provider to unblock port 25, or use a mail relay (SMTP relay like SendGrid or Mailgun) configured in Postfix.

Check Postfix logs for delivery errors:

tail -f /var/log/mail.log

Can't connect to IMAP from mail client

Verify Dovecot is running and port 993 is open:

systemctl status dovecot
ufw status | grep 993

Emails going to spam

Set up SPF, DKIM, and DMARC DNS records for your domain. Minimal SPF record:

TXT  @  "v=spf1 ip4:YOUR-SERVER-IP ~all"

Also make sure your server IP has a valid reverse DNS (PTR) record set at your hosting provider.

Database Issues

Can't connect to MySQL — access denied

The MariaDB root password is stored in /root/.my.cnf. Log in with:

mysql -u root

If that fails, check /etc/hst-suite/.env for the saved password, or reset it:

systemctl stop mariadb
mysqld_safe --skip-grant-tables &
mysql -u root -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewPassword';"
systemctl restart mariadb

Log Locations

Still Stuck?

Check the FAQ for more answers, or review the full installer output:

cat /var/log/hst-install.log | grep -E "ERROR|FAIL|WARN"