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:

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

   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:

   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 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.