Setup and joining nodes

Master setup paused after a reboot

What it means: This is expected, not a failure. Two steps in the master’s setup can trigger a restart: system settings (turning on a low-level memory setting the cluster software needs) and, after a kernel upgrade, the software update step. The wizard resumes on its own once the machine comes back and its agent reconnects.

Fix: Watch the live progress. There’s nothing to click. If it seems stuck, confirm the machine is actually back on the network and its own management service is running:

systemctl status buddy-agent
sudo journalctl -u buddy-agent -n 50

There is deliberately no timeout on this wait: if the machine never comes back, the setup simply stays parked on this step, which is exactly what the screen is telling you by not moving on.

On an older build you may see the reboot step itself marked failed with a message like “orphaned: buddy-server restarted before this task completed” even though the reboot actually worked; the setup resuming afterwards is the proof it did. This was a reporting-only defect, fixed 2026-07-22; trust that the setup moved on, not that stale label.

If that didn’t work: If a node comes back under a different name than you gave it during setup — and you notice what looks like a second copy of it in your node list — this was a real, now-fixed bug (2026-07-10): the hostname you set could be silently reverted by the machine’s own first-boot configuration before Buddy re-registered it. Current builds prevent the name from being reverted, and a node set up before the fix had its name corrected automatically. If you still see this on a build from after that date, it means the fix genuinely didn’t take on that machine, which is worth a fresh look rather than assuming it’s the known issue.

A worker won’t join

What it means: Add node can fail for several distinct reasons: the network, the credentials, the machine’s own specs, or a leftover Kubernetes installation on the worker from a previous attempt.

Fix: Work through these in order:

• Same local network required. The master and the worker must be on the same local network, since the secure connection between them assumes they can reach each other directly.
• SSH must be reachable. During Add node, SSH has to answer on the worker and the credentials you gave have to be valid. They’re used once, for this step only, and never stored afterwards.
• Read the compatibility check. Before anything is changed on the worker, discovery checks its processor architecture, operating-system version and minimum memory/disk. Review its verdict for the specific blocker named.
• “Specs not read yet” isn’t a compatibility failure. A worker that’s still settling — cloud-init still finishing, say — can leave its specs briefly unreadable. Buddy treats that as unknown, not as a failed check; press Retry and it re-reads only what’s missing, which is fast on an already-settled machine. A genuine incompatibility (wrong architecture, too little memory or disk) still names the specific blocker once the specs are actually read.
• Watch the wizard’s own live logs. A failed add can be retried safely, or rolled back cleanly, from where it left off.
• A leftover Kubernetes install on the worker. If a previous attempt left a standalone Kubernetes server process running on the worker, or its own management agent stuck inactive, joining tears that down automatically as part of the same flow: see A node’s Kubernetes health shows down, with a reason for the full failure class and what a repair does.

If that didn’t work: Export a diagnostics bundle from the panel (the Diagnostics button) and check the worker’s own log: sudo journalctl -u buddy-agent -n 50 on the worker itself, over SSH.