Troubleshooting

First two commands

sudo apcli status      # is the daemon running, and which version
sudo apcli doctor      # audit every site's server block, PHP pool, docroot and certificate

apcli doctor is read-only and works whether or not the daemon is up. Exit code 0 means everything is consistent, 1 means drift was found, 2 means it could not run. -v prints every check; --json is for monitoring. Run it with sudo, or the certificate checks are skipped because the certificate directory is root-only.

The panel does not load

1. sudo apcli status. If aurapaneld is inactive: sudo apcli restart, then apcli logs for the reason.
2. If it is active but https://<ip>:8443 does not answer, the block is a provider firewall or security group without 8443. UFW on the host already allows it.
3. After an update, if the panel looks broken or "offline", reload the page once; releases since 1.19.1 return a real 404 for stale assets so the browser's service worker refreshes itself. If the update itself failed, the updater rolls back automatically and writes why to /var/log/aurapanel-update.log.

A watchdog timer probes the panel's health every minute and restarts the daemon after three consecutive failures, so a stopped daemon usually recovers by itself within a few minutes.

Every change is refused with "a valid license is required"

The trial has ended or the licence has expired, been revoked or been unbound: the panel is read-only (HTTP 402 on any change). Sites keep running. Open Licence, press Refresh to re-check, or activate. During a network outage an activated panel keeps full access for 14 days. See trial and licence.

A site returns 502

• PHP site: sudo apcli doctor. Two findings cause this: "vhost fastcgi_pass=… but pool listen=… (sockets diverge — every request will 502)", and a pool that "exists in MULTIPLE PHP versions" after a version switch. The doctor prints the fix for each; for drift, delete and recreate the site through the panel.
• Node.js site: the app is not listening on PORT. The site's Backend card says so: "Your app keeps exiting (restarted N×) — it isn't listening on the port… Make sure your app listens on process.env.PORT." Check journalctl -u aurapanel-site-<domain> for the crash; common causes are a wrong entry file, a missing npm install, or a hard-coded port. Node.js sites.
• Python site: gunicorn is missing or cannot import the module. The journal shows ModuleNotFoundError or the panel's "gunicorn is not installed at /usr/bin/gunicorn" message. Python sites.
• Docker site: "Container is running but not answering HTTP on 127.0.0.1:<port>": the container port in the compose file must match what the app listens on inside the container, and the app must bind 0.0.0.0, not localhost. Docker Compose sites.

A PHP site returns an empty page with status 200

The server block and the PHP pool disagree about the site user: apcli doctor reports "DRIFT: vhost says user=X but pool says user=Y". Delete and recreate the site through the panel; sites created by current releases cannot get into this state.

HTTPS is not issued

The site's overview shows the last ACME error. Work through HTTPS certificates: DNS pointing elsewhere, port 80 blocked, or a Cloudflare proxy answering the challenge (switch to DNS-01). On the server: journalctl -u aurapaneld | grep acme. apcli doctor warns 30 days before a certificate expires and errors at 7.

Cloudflare shows error 525 or 520

Cloudflare reached the server, but the TLS handshake failed. The server completes handshakes only for hostnames it has a server block for; a hostname with no site (a forgotten subdomain, a domain you meant to redirect) is rejected at the handshake and Cloudflare reports 525. Create the site, or a redirect, for that hostname. A 520 or 525 on a hostname that does have a site usually means Cloudflare's SSL mode is not Full.

Cloudflare shows error 524 during an upload, import or restore

Cloudflare drops responses that take longer than about 100 seconds. The panel keeps long operations off that path: uploads are sent in 90 MB chunks with resume, and backups and restores run as background jobs you poll. If you are proxying the panel's own domain through Cloudflare and still see 524 on a long action, run the action from the server address instead, or leave the panel hostname unproxied (grey cloud).

"… step failed — open Logs → app for the details."

The dependency install or build for a Node.js site failed. The full output is in the site's Logs tab under app.

A framework site 403s or serves the wrong directory

Applications that serve from a subdirectory (Laravel and Moodle 5 use public/) need Settings → General → Document root set to that directory. Since 1.19.5 an override is honoured on every render.

A database or nginx is down

sudo apcli server status
sudo apcli server restart mariadb      # nginx, postgresql, redis-server, docker, php8.4-fpm …

The panel refuses to restart units it is not responsible for. Database actions in the panel report "MariaDB isn't running on this host. Start it from Instance → Services…" when this is the cause.

The server is slow and a service is restarting constantly

The Runaway services card on the Server page lists services the watchdog has flagged. Crash-looping services are already throttled to half a core; a CPU hog has a one-click Throttle. Find the cause in that unit's journal, fix it, then Remove cap. Runaway service watchdog.

Locked out of the panel

sudo apcli user list
sudo apcli user passwd admin@example.com --generate

Root on the server can always reset a panel password, in any licence state. Lost password or authenticator.

Start again

sudo aurapanel-uninstall removes the panel and everything it installed, including sites, their Linux users and home directories; --keep-databases preserves MariaDB and PostgreSQL. Back up first. A reinstall does not restart the 30-day trial.

Still stuck

Send the output of apcli status, apcli doctor -v and the relevant journal lines through the contact form. Customers can also reach us from the portal.