Troubleshooting

The dashboard is unreachable#

1. Check the container health of the core stack on the main node: sudo docker ps — every zensailor-* container should be healthy or running.
2. If anything is down, run the repair tool: Repair.
3. Confirm ports 80/443 are reachable from outside (curl -I from another machine). Router conflicts with an existing web server are the classic cause — see Requirements and Plans.

Certificates fail to issue#

• The DNS A/AAAA record must resolve to the server before you add the domain — Let's Encrypt validates at request time. Fix the record and re-add the domain (or re-request from the domain's settings).
• Port 443 must be reachable from the internet.
• For internal hostnames (.local, .lan, an IP), use the installer's local/profile options — self-signed or no TLS — instead of public issuance. See Domains and SSL.

A deployment stays queued#

The queue means slots are full or a deploy window is closed.

• zensailor system queue shows active and queued work, with reasons.
• A window-deferred deployment displays why it is waiting and when it will run — see Deploy Windows.
• Rollbacks and restores run immediately; only new change waits.

A service with volumes will not deploy#

If the node holding its data is unavailable, the deploy waits and tells you which node it needs. Either bring the node back, or run a volume migration to move the data to a healthy node — see Storage Across Nodes.

A node is stuck offline#

• Agents heartbeat every 30 seconds; after 90 seconds of silence the node is marked offline. Check the node's Docker and agent container, and its network path to the control plane (agent port).
• Node pressure (disk/memory/CPU) also gates scheduling — the node list shows the pressure state and notifications explain what recovered.

Migrations get stuck#

Prisma migration failures on upgrade (P3009-style) are resolved by the repair tool — run sudo ./fix.sh and it auto-heals them. See Repair.

Storage fills up#

• zensailor system prune reclaims unused Docker resources across nodes — pruning never touches managed bind mounts.
• The Storage page shows every managed folder and what it holds — see Storage Management. Old snapshots are removed by retention after successful backups only.