Migrating to an SSD

“Migrate OS to SSD” is missing or blocked

What it means: This action is only offered on a node that’s actually eligible, and Buddy tells you exactly which condition it’s failing:

not a Raspberry Pi 5,
no NVMe disk attached via the M.2 HAT+, or one too small,
firmware too old to boot from NVMe at all,
the operating system is already on the NVMe, or
an unrecognised disk layout.

Fix: Fix the specific condition named. For old firmware, use the firmware-update action the panel links directly from this check. Buddy never re-flashes firmware on its own. Then re-check.

If that didn’t work: If the check names an unrecognised disk layout, that node’s disk isn’t in a shape this flow currently understands; it isn’t something to fix by retrying.

The node didn’t come back booted from the NVMe

What it means: The migration keeps the screen parked at “rebooting — waiting for the node to come back on NVMe” until it can confirm the boot actually happened. The very first NVMe boot can be slow. This alone can look stuck for longer than you’d expect.

Fix: Give it a minute first. If it still hasn’t come back:

Power the node off.
Physically remove the microSD card.
Power it back on. With the card absent, the firmware falls through the boot order to the NVMe.

If it boots this way, put nothing back in the card slot and run the retire step. If it still doesn’t boot, put the microSD back in — the node boots from it exactly as before, unharmed — and check the firmware update mentioned above.

If that didn’t work: Nothing on the microSD is touched during any of this, so the node is never left unable to boot at all. If NVMe genuinely won’t boot even with the card removed, the disk or its connection to the M.2 HAT+ is the next thing to check physically.

Boot order didn’t change / it still boots from the microSD

What it means: The boot order — NVMe first, microSD as a fallback — is meant to be set automatically as part of the migration. Occasionally a firmware quirk ignores that setting, and the node simply keeps booting from the card instead.

Fix: Nothing is lost in this case: re-run the migration; it picks up cleanly from wherever it left off rather than starting over. If it still doesn’t take, check the node’s firmware version against what’s expected.

If that didn’t work: If re-running doesn’t change the boot order either, treat it as the firmware condition from “‘Migrate OS to SSD’ is missing or blocked,” above, and update the firmware first.

“Retire microSD” is refused

What it means: Retiring the card is gated on two things both being true: a verified NVMe boot, and the microSD being physically gone. This is deliberate: retiring is the point of no easy return, so Buddy checks rather than takes your word for it.

Fix: Power the node off, physically remove the microSD, power it back on, then retry. Buddy re-verifies the node boots from NVMe alone before it records the retire.

If that didn’t work: If the node won’t boot with the card removed at all, see “The node didn’t come back booted from the NVMe” above before trying retire again.

I want to undo a migration

What it means: Whether you still can, and how, depends on how far the migration got.

Fix:

Before you’ve retired the microSD: choose Abort, or simply re-insert the microSD and reboot. The boot order rolls back and the node boots from the card exactly as it did before; the live microSD is never written to at any point during the migration itself.
After you’ve retired the microSD: the operating system now genuinely lives on the NVMe only. Going back means re-flashing a fresh microSD card, the same way you’d set up any node.

Once you’ve retired the microSD, there’s no one-click way back. Re-flashing a card is your only route to the old setup.

If that didn’t work: If Abort doesn’t cleanly return the node to booting from the microSD, check “Boot order didn’t change” above. The same firmware quirk that can block the forward migration can also block the rollback.