Skip to content
MZPanel MZPanel
Troubleshooting Fix a server that won't come online, stuck or failed jobs, SSL issuance, and backup errors.
CtrlK

Troubleshooting

Most problems are visible from the dashboard. Start with the server’s status and its activity / job log, then work down this list. On the box itself, every panel action maps to an mz … --json command you can run over SSH to see the raw result — handy when the dashboard only shows a failure summary.

Agent won’t come online

Section titled “Agent won’t come online”

The agent dials outbound to wss://ws.mzpanel.com:443 — the VPS opens no inbound ports. If a server stays offline after install:

  1. Check the service is running. On the VPS:

    Terminal window
    systemctl status mzagent
    journalctl -u mzagent -f

  2. Check outbound HTTPS (443). The VPS must reach ws.mzpanel.com and api.mzpanel.com on port 443. A firewall or egress proxy that blocks outbound 443 will keep the agent stuck in reconnect (exponential backoff up to 60s). Test:

    Terminal window
    curl -fsS https://api.mzpanel.com/healthz

  3. Check the token. The install token is valid for 1 hour. If install was slow or retried after expiry, generate a fresh Add server command and re-run it. Once registered, the agent uses a long-lived token — but if the server was revoked or re-issued in the dashboard, the old token stops working and you must re-register.

  4. Check the plan quota. If your workspace is at its VPS quota, the control plane refuses the connection until you free a slot or upgrade. See Plans & pricing.

Job stuck or failed

Section titled “Job stuck or failed”

Operations run as jobs dispatched to the agent over WebSocket.

  • Stuck “queued”: the agent is likely offline — the API queues jobs and delivers them on reconnect. Fix connectivity (above) and the job will run.
  • Failed: open the job’s log in the dashboard. The result includes the exit code and error; the streamed stdout/stderr shows what the on-box engine reported. Re-run after fixing the underlying cause (e.g. a busy package manager, low disk, or a service that’s down).
  • Long-running job timed out: heavy operations have a time budget (a backup run, for example, gets up to 30 minutes). Retry, and if it consistently times out, check server load and disk space.

SSL issuance fails

Section titled “SSL issuance fails”

SSL uses Let’s Encrypt via the agent (ssl.issue / ssl.renew jobs). Common causes:

  • DNS not pointing at the server. The domain’s A/AAAA record must resolve to the VPS for the HTTP-01 challenge. Verify the record has propagated before retrying.
  • Port 80 blocked. HTTP-01 needs inbound port 80 reachable on the VPS during validation.
  • Rate limits. Let’s Encrypt limits repeated attempts for the same domain. Wait before retrying a domain that has failed several times.
  • Wildcard / DNS-01. Wildcard certificates require DNS-01 and a configured DNS provider (Plus plan). Make sure the integration is connected.

Backup errors

Section titled “Backup errors”

Backups run as per-site archive jobs (backup.v2-run) that produce a .tar.gz plus a manifest, pushed to the job’s destination. Restores, existence checks and deletes are the matching backup.v2-restore / backup.v2-verify / backup.v2-delete jobs.

  • Run fails immediately with “server offline”: the agent isn’t connected — bring the server online (see above), then run the job again.
  • Local / disk failures: usually disk space on the VPS while staging the archive — check free space and prune old snapshots.
  • Offsite destination fails: verify the destination credentials and that the remote (S3 / R2 / B2 / Google Drive) is reachable. Offsite backup is a Plus feature; make sure your plan includes it.
  • Encrypted backups: Advanced (encrypted) jobs seal each archive with a per-server passphrase. You must keep that passphrase to restore — download it from the backup settings; without it an encrypted archive cannot be recovered.
  • Restore stalls or reports missing: the daily existence check flags snapshots whose archive is no longer at the destination. If a restore stalls, open the job log for the exit code and confirm the archive still exists at the destination.

Still stuck?

Section titled “Still stuck?”

Use the in-dashboard Assistant (the Ask AI button in the top bar) to get help or escalate to a human — the drawer keeps your conversation history and can hand off to support. When reporting an issue, include the server ID and the job ID from the activity log; they tie directly to the audit record. See Security model.

Section titled “Related”