Storage & apps
A disk doesn’t appear / a “Prepare” option is missing
What it means: Only empty, unprepared disks can be turned into a pool. A disk that already has a partition or filesystem on it shows up on the Storage screen but without a Prepare option; Buddy won’t overwrite something that might already hold data without you saying so explicitly. Discovering a newly plugged-in disk also isn’t instant: it runs on a light periodic check, and again whenever a node’s agent reconnects.
Fix: If the disk isn’t preparable because it already has something on it, wipe it first (outside Buddy) or attach a blank disk instead. If it simply hasn’t appeared yet, give it a few seconds. The next discovery pass picks it up.
If that didn’t work: Confirm the disk is actually visible to the node’s operating system at all (reseat the connection if it’s USB) before assuming it’s a Buddy-side issue.
A pool shows “degraded”
What it means: The pool’s backing disk has gone missing, most often because a USB disk was pulled without being detached first.
Fix: Re-attach the disk. The pool recovers to ready automatically on the next discovery pass: there’s no action to trigger by hand. Any app using storage on that pool will be unhappy in the meantime, since its data isn’t reachable until the disk is back.
If that didn’t work: If re-attaching the same disk doesn’t clear the degraded state, the disk itself may be the problem; check it’s healthy at the operating-system level on the node that holds it.
“Detach” / “Delete” is refused
What it means: These guards exist to protect your data: a pool can’t be detached while it still holds any storages, a storage can’t be deleted while an app is using it, and a node holding a pool can’t be removed from the cluster.
Fix: Work backwards through what’s using the thing you’re trying to remove: uninstall the app, then delete the storage, then detach the pool. See Remove an app and its storage for the full order.
If that didn’t work: If you’ve already removed everything you can see using it and the action is still refused, check for another app or storage you may have missed on the same pool.
Preparing a disk asks for confirmation, and there’s no undo
What it means: Preparing a disk erases everything already on it. This isn’t a soft warning, it’s a real, irreversible step, which is why it’s the one confirmation in Storage you can’t skip past.
There is no undo for preparing a disk. Make sure it’s the right disk before you confirm.
Fix: Not applicable: this is expected behaviour, not something to work around. Double-check the disk’s size and model shown on the confirmation before proceeding.
If that didn’t work: If you prepared the wrong disk, there’s no recovery path from inside Buddy. Whatever was on it is gone.
“Prepare” fails with a filesystem error
What it means: Two distinct causes show up this way:
mkfs.xfs … not found in $PATH— fixed; you’d only see this on an older node agent. The node’s operating-system image was missing the XFS filesystem tools (this is normal on Debian and Raspberry Pi OS images; Ubuntu Server images ship them). A current agent installs what it needs on its own before touching the disk.- The kernel can’t mount the filesystem — that node genuinely can’t host an XFS pool.
Fix: For the missing-tools case, update the node’s agent and retry, since a current agent handles it automatically. For the kernel-can’t-mount case, prepare the disk as ext4 instead of XFS.
Either way, the failed attempt has already erased the disk. Expect it to come back blank and offerable again. That’s expected, not a second failure.
If that didn’t work: If ext4 also fails to mount on that node, the disk or the node’s kernel is worth checking directly, outside Buddy.
A package install fails with “cluster unreachable”
What it means: Kubernetes isn’t ready to accept new work yet: either the master’s own setup
hasn’t finished, or the node meant to hold the install hasn’t finished joining the cluster. The panel
shows this as a 503 response from the cluster.
Fix: Finish Run the setup on the master first if you haven’t, or wait for the target node to finish joining (see A worker won’t join if it’s stuck). Retry the install once the cluster shows ready.
If that didn’t work: If the cluster is otherwise healthy and this keeps happening, check the specific node the install would land on for the same offline/NotReady symptoms covered in A node offline or NotReady.
Where does my app’s data live, and does it move with the node?
What it means: This depends entirely on which storage tier you picked when you created the storage:
- Node-local — the app is pinned to the disk’s own node, for full local-disk speed. Its data never leaves that node.
- Shared — the app can run on any node, because the storage is reached over the cluster’s own private network rather than a local disk.
Either way, the data lives on your storage and survives the app’s pod being restarted. Restarting the app doesn’t touch the data.
Fix: Not applicable: this is how the two tiers are designed to behave, not a fault. If an app seems pinned to a node you didn’t expect, check which tier its storage uses on the Storage screen.
If that didn’t work: See Prepare a disk and create a storage for how the two tiers are chosen, and its note on what “shared” does and doesn’t protect against.