Troubleshooting

Fixes for common problems: panel unreachable, lost password or 2FA, SSL and mail failures, the busy page, failed updates, licenses, and getting support.

Updated Oct 7, 2026 · 6 min read

Start with the doctor. It checks the services, the panel, the database, disks, memory, the certificate, the clock and the last update, and tells you what to do about each problem:

zopanel ctl doctor

The sections below cover the problems we see most often. All commands run as root on the server.

I cannot reach the panel

The panel listens on port 8888: https://YOUR-IP:8888, or https://your-panel-domain:8888 once you set a panel domain. On the IP address the certificate is self-signed, so the browser shows a warning the first time.

1. Is the panel running?

   systemctl status zopanel zopanel-agent
   journalctl -u zopanel -n 50
   

2. Is the port open? The installer allows SSH, 80, 443 and 8888 in UFW. Check with ufw status. If your provider has a cloud firewall or security group, open 8888/tcp there too.
3. Is your IP allowed? If Restrict panel access is set and your IP changed, clear the list:

   zopanel ctl allow-ip --clear            # allow everyone
   zopanel ctl allow-ip 203.0.113.10       # or only your new IP
   

4. Is your IP banned? After 8 failed logins within 15 minutes, fail2ban blocks the address on port 8888 for 1 hour. Unban it with:

   fail2ban-client set zopanel unbanip 203.0.113.10
   

   An administrator can also do this from another address in Security → Unban.

I forgot the admin password

zopanel ctl reset-password admin

This prints a new random password. You can choose one with --password. All of that user's sessions are signed out and their API tokens are revoked. The same command works for any panel user.

I lost my two-factor device

zopanel ctl disable-2fa admin

Sign in with your password, then set up 2FA again in My account. If Require two-factor authentication is on, you are asked to set it up at sign-in.

Let's Encrypt certificate fails

Check where a domain points:

dig +short example.com A
curl -I http://example.com/

You do not have to retry by hand. AutoSSL checks every hour for sites without a certificate and requests one as soon as every address of the domain is this server's. A domain that still points to the old server, or partly elsewhere, waits. Failed attempts back off from 2 hours up to a day. Certificates renew automatically 30 days before they expire. Failed renewals are retried after 1, 2 and 4 days, and you get an SSL renewal failed alert.

For the panel's own certificate, use Settings → General → Panel domain & SSL → Issue certificate. More in SSL certificates.

Mail is not delivered

Open Email, choose the domain, and run Mail delivery check. It checks MX, SPF, DKIM, DMARC, reverse DNS (PTR), outbound port 25 and blocklists, and tells you the record to add.

• Outbound port 25 blocked. Many VPS providers block port 25. Ask them to open it, or send through an SMTP service: as administrator, use Email → Outgoing mail relay (smarthost) (SendGrid, Mailgun, Amazon SES, Brevo…).
• Reverse DNS (PTR). Ask your VPS provider to set the IP's reverse DNS to your mail hostname, such as mail.example.com.
• Blocklists (Spamhaus, SpamCop, Barracuda). First find what is sending spam. A hacked website is the usual cause. Check Email → Mail queue and Sending limits, then request delisting on the blocklist's website. ZoPanel checks the server IP once a day and sends a Server IP on a blocklist alert.
• Mail queue growing. 300 or more waiting messages trigger an alert. Look at the queue for one sender or one remote server that refuses mail.
• DKIM missing. Publish the DKIM TXT record exactly as shown in the domain's DNS table. See Email.

A website shows a "busy" page

PHP and app websites show a "busy, please retry" page (HTTP 503, Retry-After: 30) when PHP or the app cannot answer: it is overloaded, restarting or out of memory. Search engines treat it as temporary. Causes, from most to least common:

1. The account hit its package limits. Open the website's Logs tab and click Run diagnostics. "Too many simultaneous PHP requests" means PHP workers is too low. "Process killed (out of memory)" means the package's RAM (MB) is too low. Raise them in Packages, or add caching.
2. The server is short of memory. Look at Tuning and the account's usage history (Accounts → Usage history). Under heavy memory pressure ZoPanel stops idle PHP pools and drops requests that have queued too long, so the server recovers once the load stops.
3. Bots or a traffic burst. Turn on the Page cache and a Request rate limit in the website's PHP & config tab.
4. The app is not running. For Node.js, Python or Docker apps, check the Deploy or Docker tab output and restart the app.

See Performance and capacity for how ZoPanel handles overload.

An update failed

Updates are checked and roll back by themselves. If the new version is not healthy within 3 minutes, the previous binary and database are restored, and you get a Panel update failed or rolled back alert. To roll back by hand, for example for a problem you notice later:

zopanel rollback          # previous version, current database
zopanel rollback --db     # also restore the database saved before the update

zopanel ctl doctor shows the result of the last update. If an update keeps failing, open a ticket with a support bundle (see below).

The license is refused

Check the license in Settings → License and on the server with zopanel ctl info. If a license is not valid, the panel runs on the Free plan (3 accounts and 10 websites).

See Licensing for plans and activation.

Where are the logs?

Getting help

1. Run the doctor and keep its output:

   zopanel ctl doctor
   zopanel version
   zopanel ctl info
   

2. Create a support bundle:

   zopanel ctl support-bundle
   

   It writes /root/zopanel-support-<date>-<time>.tar.gz with the doctor report, versions, failed services, resource usage, the last 500 lines of the main logs, and the configuration. Passwords, secrets, tokens and keys are removed.
3. Open a ticket. If you have a ZoPanel account, go to Support tickets → New ticket and choose the license concerned. Otherwise, use the support page. Choose the topic Technical help, paste the doctor output and say what changed before the problem started. Keep the support bundle ready: the team may ask you for it.

Never send passwords, private keys or your recovery key in a ticket.