Troubleshooting

Most problems are visible from the dashboard. Start with the server’s status and its activity / job log, then work down this list.

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:

Check the service is running. On the VPS:
Terminal window
```
systemctl status mzagent
journalctl -u mzagent -f
```
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
```
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.
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 Billing & plans.

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 job_done 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: very heavy operations have a time budget. Retry, and if it consistently times out, check server load and disk space.

SSL issuance fails

SSL uses Let’s Encrypt via the agent. 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

Local backup fails: usually disk space on the VPS — check free space and prune old local backups.
Offsite backup fails: verify the destination credentials and that the remote (S3/B2/etc.) is reachable. Offsite backup is a Plus feature; make sure your plan includes it.
Restore issues: restores stream progress in the dashboard. If a restore stalls, check the job log for the exit code and confirm the backup archive is intact.

Still stuck?

Use the in-dashboard Assistant to get help or escalate 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.