Troubleshooting
First checks
bash
systemctl status hostpanel hostagent --no-pager
journalctl -u hostpanel -u hostagent -n 150 --no-pagerIf something is broken after a manual change, Settings → Updates → Repair installs the current version again and puts files and services back. See Repair.
The panel
| Problem | What to do |
|---|---|
| The page does not open | Check port 8443 is open in your provider's firewall and that hostpanel is running. |
| Certificate warning in the browser | Normal with the self-signed certificate. Give the panel a domain and a real certificate: SSL. |
| "The agent is not running, so the panel cannot change anything" | sudo systemctl restart hostagent, then look at journalctl -u hostagent. |
| "The form expired or came from another site" | Reload the page and try again. Sign out and in if it repeats. |
| "Too many failed attempts" | Wait for the time shown, or sign in from an admin address. |
| Forgot the password | sudo merp reset-admin --username NAME on the server. |
| Lost the 2FA phone | Use a recovery code, or sudo merp reset-2fa NAME. |
| Locked out by the firewall or a country rule | From the provider's console: sudo /opt/hostpanel/bin/hostagent firewall-reset |
| "Safe Mode is on" | An admin ends it in Server protection, or sudo /opt/hostpanel/bin/hostagent safe-mode off. |
| "Your role does not allow this" | Ask an admin to change your role or give you the site. |
Sites
| Problem | What to do |
|---|---|
| DNS badge: "No DNS record" or "DNS points elsewhere" | Add or fix the A record at your DNS provider to the server IP. |
| 502 Bad Gateway on an app site | Nothing listens on the app port. Start your app, or change the site type. |
| "This site uses PHP X, which is not installed" | Install that version from the App Store, or pick another on the site page. |
| 403 / blank page on a React/Vue site | The site folder must point to the build (public_html/dist) and contain index.html. |
| 404 on refresh in a single-page app | Use the React / Vue app type, not Static files. |
| "The folder … does not exist in the site yet" | Create it in the file manager, then set the site folder. |
| Upload too big | Raise max upload on the site page and, if needed, the PHP version's upload limit. The smaller wins. |
| WordPress cannot update plugins | Check Server protection → Outgoing connections is not set to Only the list for that site. |
A plugin needs exec | Tick Allow PHP to run programs on the site page (admins). |
SSL
| Problem | What to do |
|---|---|
| "Set the Let's Encrypt email first" | Enter it on the SSL page. |
| Certificate request fails | The domain must point to this server and port 80 must be open. Wait a few minutes after changing DNS. |
| Too many redirects behind Cloudflare | Cloudflare SSL mode must be Full (strict). See Cloudflare. |
| Error 526 behind Cloudflare | The site needs a valid certificate (Let's Encrypt or an Origin certificate). |
| An extra domain is "Not in certificate" | Fix its DNS, then press Update certificate. |
Web server and databases
| Problem | What to do |
|---|---|
| "The web server rejected the change, so nothing was changed" | Your edit has an error; the message shows the line. The old config is still live. |
| Turning on the WAF fails with "unicode map file" | Fixed in 1.4.4. Update the panel. |
| A rule of the WAF blocks normal use | Turn that rule off in Traffic, or put the WAF back on Watch only. |
| "The database server is not running" | Databases → Service → Start, and read its log. |
| "MariaDB/MySQL is not installed" | Install it from the App Store. |
| Database connection refused in your app | Use host localhost, the database's own user and its password. Reset the password if lost. |
Email
| Problem | What to do |
|---|---|
| Mail to Gmail/Outlook never arrives | Outgoing port 25 is probably blocked. Ask your provider or use an SMTP relay. |
| Mail lands in spam | Add all DNS records (SPF, DKIM, DMARC) and set reverse DNS (PTR) to the mail host name. |
| Mail apps warn about the certificate | Get a certificate for the mail host name on the Email page. |
Get help
Send a screenshot of the page and the output of:
bash
journalctl -u hostpanel -u hostagent -n 150 --no-pagerFor the firewall add sudo nft list ruleset | head -80.