HF PanelTroubleshoot the installation
What to do when the installer stops, the messages it shows, and the common problems right after installing.
When a step fails, the installer marks it stopped, prints the last lines of its log and exits. Nothing is left half-way that a re-run can't finish: fix the cause, then run the same command again.
Read the log
tail -n 50 /var/log/hostfog-install.log
Each step starts with a line like ==> [12/23] MariaDB, so you can see where it stopped.
The installer stops before it starts
These checks run before anything on the server changes.
| Message | What to do |
|---|---|
Run as root (sudo -i). |
Log in as root, or run sudo -i, then the command again. |
HF Panel needs Ubuntu 22.04, 24.04 or 26.04 LTS, or Debian 12 or 13 … |
Reinstall the server with a supported system. |
… looks like a container (OpenVZ/LXC/Docker); ask your provider for a KVM VPS. |
Use a full virtual machine (KVM, VMware, Hyper-V, Xen) or a dedicated server. |
HF Panel runs on 64-bit Intel/AMD (amd64) or ARM (arm64) servers … |
Use a 64-bit server. |
HF Panel needs at least 1 GB of memory … / … at least 5 GB of free disk space … |
Choose a bigger plan, or free disk space. |
Another control panel is installed on this server … |
Start again on a fresh server. |
Download failed — check the server's internet connection. |
The server can't reach the download server. Check its outgoing connection and DNS. |
The download is not signed … / The download is damaged (checksum mismatch) … |
Run the command again. If it keeps happening, contact support. |
The licence key is refused
| Message | What to do |
|---|---|
That is not a licence key (HFL-XXXXX-XXXXX-XXXXX-XXXXX). |
Check the key for typing mistakes. |
not accepted — check the key, or type T for a free 14-day trial |
The key doesn't exist, isn't active, or is for another server's IP. Check that the server's public IPv4 address is the one you licensed. |
… for another server IP |
Move the licence to this server's IP in the licence portal (see Licensing), or install on the licensed server. |
Could not reach the licence server … |
The server's outgoing HTTPS is blocked. Open it and try again. |
HF Panel needs a licence key. Run this command in a terminal … |
There is no keyboard to ask on. Pass --licence HFL-… on the command line. |
| A trial can't be started | Each server IP and each email address gets one trial. Enter a licence key instead. |
A step fails
Packages. Another program is using the package manager (an automatic update on first boot, cloud-init), or a
package source is broken. The installer waits up to 10 minutes for the lock. Check with apt-get update, fix or
remove the broken source in /etc/apt/sources.list.d/, then run the command again.
Panel certificate. Let's Encrypt could not reach the server. Check that port 80 is open (also in the provider's cloud firewall) and that the names point at this server. The installation carries on with a temporary certificate, and the real one is fetched by itself within 5 minutes of DNS being right.
Email. Usually IPv6 is configured on the server but doesn't work. Fix the network or remove the IPv6 address, then run the command again.
Disk full. df -h / shows it. Free space or grow the disk, then run the command again.
MongoDB databases could not be set up. The installation carries on without them. Install them later under
Server Admin › System › Software versions. The log is /var/log/hostfog-mongo-install.log.
The TO DO list in the summary
The summary's TO DO list names anything the installer could not finish. Common items:
| Item | What to do |
|---|---|
| DNS records still missing | Add them (hf-panel dns-setup --check). Each name gets SSL by itself within 5 minutes. |
Create your admin login: hf-panel create-admin |
The installer had no keyboard. Run the command. |
| The "server is ready" email could not be sent | Send it later: sudo -u hostfog /usr/local/hostfog/bin/hf-api notify server-ready --force |
| The licence could not be confirmed yet | Open Server Admin › Billing › Licence and click Check now. |
| The HF API service (hostfog-api) is not running | Look at journalctl -u hostfog-api, fix the cause and run the installer again. |
| Some sites could not be migrated | Check nginx -t and apache2ctl configtest. |
After the installation
I can't open the panel. Use the address with the port: https://server.yourdomain.com:8443. Without the port,
the name goes to your website. If it still doesn't open, port 8443 is closed in your provider's cloud firewall.
The browser shows a certificate warning. The name didn't point at the server during the installation. Fix its A
record; the real certificate replaces the temporary one within 5 minutes. To ask for it straight away:
hf-panel ssl-now.
api.yourdomain.com shows "403 Forbidden". That is expected in a browser: the API answers programs only, at
https://api.yourdomain.com:2087/v1.
Email goes to spam. Set the reverse DNS (see DNS setup), then check Mail health until SPF, DKIM and DMARC are green. Ask your provider to open outgoing port 25 if mail isn't delivered at all.
I forgot the admin password. Run hf-panel reset-password <username> on the server.
Still stuck?
Contact us with:
- your system and version:
cat /etc/os-release - your HF Panel version:
cat /etc/hostfog/VERSION - the last 50 lines of
/var/log/hostfog-install.log, with passwords removed
More problems and fixes: Troubleshooting.