Troubleshooting

Install hangs or fails

"E: Could not get lock /var/lib/dpkg/lock"

Another package operation is running (likely unattended-upgrades). Wait 2 minutes and re-run the installer — it's idempotent.

MariaDB install fails after mail packages

This was a known issue in installers before 1.0.5 — the cumulative deb-systemd-invoke state from the Postfix/Dovecot/OpenDKIM installs would silently break MariaDB's post-install hook. Upgrade to the latest installer (it now installs MariaDB before the mail stack).

Caddy build hangs at "downloading xcaddy"

Network issue reaching api.github.com. The installer caps the build step at 90 seconds and falls back to the package manager's caddy. If you want WAF support specifically, you can re-run the install with --skip-waf and add it later.

Panel won't start

"internal verification failed"

The binary's self-integrity check tripped — the SHA of the file on disk doesn't match what our license server expects for that version. Common causes:

• You manually copied a binary from another server with a different version
• An update was interrupted mid-write — re-run the installer to fetch a fresh copy
• Disk corruption — check dmesg | tail

"license bootstrap failed"

The panel can't reach our license server at first start. Check that outbound HTTPS works and DNS resolves license.novapanel.dev. If you're behind a strict firewall, allowlist that hostname.

Login keeps redirecting to the login page

JWT cookie isn't being accepted by your browser, usually because the panel hostname doesn't match what's in your browser's URL bar. Check /etc/novapanel/config.yaml — the hostname field has to match how you're accessing the panel.

Mail issues

Outbound mail rejected as spam

SPF/DKIM/DMARC records are missing on your domain. The panel auto-generates the right values — check the Mail page in the admin panel for the records to add to your DNS.

Port 25 blocked

Most VPS providers block outbound port 25 by default to prevent spam. You'll need to either request the block be lifted (Hetzner, OVH, Scaleway will, after a verification step) or configure an SMTP relay (Mailgun, SES, Postmark) in the Mail page.

Update problems

"Updater not initialized"

The update service crashed at startup. Restart the panel: systemctl restart novapanel.

Self-update succeeds but panel still shows old version

The systemd-run swap completed but didn't restart the panel cleanly. Run systemctl restart novapanel manually.

Backups

S3 backup uploads are slow

Large databases compress before upload. The bottleneck is usually CPU during gzip — set the backup region close to your server, and prefer Backblaze B2 over S3 for cost/speed.

Still stuck?

Email support@novapanel.dev with:

• Output of journalctl -u novapanel -n 200 --no-pager
• Your panel version (novapanel version)
• What you were trying to do