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 caddyserver.com, whose build API compiles the WAF-enabled binary on demand. The installer gives that download 90 seconds, then falls back to building locally with xcaddy (180 seconds to install xcaddy itself, 480 for the build). If both fail it uses the package manager's caddy and carries on — you get a working panel without the Coraza WAF or wildcard SSL. Re-running the installer retries the build; --skip-waf does the opposite, telling it not to build the WAF module at all.

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

The panel keeps your session in the browser's local storage and sends it as an Authorization: Bearer header — no cookie is involved, so this is never a cookie or hostname mismatch. Access tokens last 15 minutes and are refreshed silently in the background; you land back on the login page when that refresh itself fails. Usual causes:

• The refresh token expired (7 days by default) or was revoked — sign in again.
• NOVA_JWT_SECRET in /opt/novapanel/config/.env changed, which invalidates every token already issued. Sign in again after any change to it.
• The server clock has drifted, so freshly issued tokens read as already expired. Check timedatectl and confirm NTP sync is on.

Being logged out after a period of inactivity is separate and deliberate — that's the Session Timeout setting in the admin panel, 30 minutes by default (set it to 0 to disable).

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