View source for Postmortems/2026-06-28 HA Blue Bootswitch

''As of: 2026-07-05 — migrated from `postmortems/2026-06-28-ha-blue-bootswitch.md`''

= Postmortem — Home Assistant "offline / won't get an IP" (2026-06-28) =

== Summary ==
The Home Assistant box (shante, <code>192.168.0.140</code>) had been powered off and boxed for
~weeks. On power-up it would not appear on the network — no DHCP lease, unreachable on
LAN and Tailscale. Root cause was '''not''' a network or HAOS-corruption problem: the
device's physical '''boot-mode toggle switch''' had been bumped out of the eMMC position,
so the board booted into its '''Petitboot recovery shell''' instead of loading Home
Assistant OS off the eMMC. HAOS never started, so nothing ever came up on the network.
Flipping the switch back and rebooting restored normal boot.

== Device identification (corrected) ==
The unit is a '''Home Assistant Blue = ODROID-N2+''', not a Green/Yellow as the docs had
it labeled. Identifying tells:
* '''Petitboot''' bootloader screen (Green uses Rockchip/U-Boot; Yellow uses Pi CM4 — neither uses Petitboot).
* A physical '''boot-select toggle switch''' on the front (eMMC ↔ SPI) — an ODROID-N2+ hardware feature.
* Blue translucent case; red (power) + blue (activity) LEDs visible through the sliding door.
* HDMI + single Ethernet on the back.

Docs updated: <code>INFRASTRUCTURE_INVENTORY.md</code>, <code>HOME_ASSISTANT_INTEGRATION.md</code>, <code>VLAN-Setup-Guide.md</code>.

== Timeline ==
* Device boxed unpowered for ~weeks (Tailscale "last seen 26d ago" ≈ 2026-06-02).
* Powered on; never got an IP. LAN ping/UI dead; Tailscale peer <code>offline</code>.
* 8-min network poll for <code>192.168.0.140</code> / <code>homeassistant.local</code> → nothing.
* HDMI attached → '''Petitboot''' menu + "Failed to launch Petitboot, dropping to a shell", <code>#</code> busybox prompt.
* Recognized Petitboot ⇒ bootloader couldn't find a bootable OS ⇒ boot/storage issue, not network.
* User flipped the front toggle switch and rebooted → got a login prompt; reconnected to LAN.
* HA Core first-boot was slow ("Loading data", login "something went wrong" while backend caught up). Settled after a few minutes.
* Confirmed back: Tailscale peer <code>active</code>, direct <code>192.168.0.140:36309</code>, real rx traffic.

== Root cause ==
Physical boot-mode toggle was in the SPI/recovery position (likely bumped while boxed),
so the ODROID-N2+ ran Petitboot's recovery shell instead of chain-loading HAOS from eMMC.

== Why login "spun then failed" right after recovery ==
Not an auth bug. A box stored unpowered for weeks does a slow first start — recorder/DB
catch-up, NTP clock resync, integration re-init. The frontend (port 8123) answers before
Core is ready, so login spins / "something went wrong" until the backend finishes. Fix:
'''wait 5–15 min, don't reboot mid-startup.'''

== Diagnostics that worked ==
<syntaxhighlight lang="bash">
# Is it on the network at all?
ping -c2 192.168.0.140
curl -sS -m8 -o /dev/null -w "%{http_code}\n" http://192.168.0.140:8123/

# Is Tailscale seeing it? ("offline, last seen Nd ago" = box truly down, not just LAN/DHCP)
tailscale status | grep -i homeassistant

# At the Petitboot # shell, check whether OS storage is even detected:
cat /proc/partitions
</syntaxhighlight>

== Prevention / follow-ups ==
* '''Leave the front toggle switch in the eMMC (HAOS-boot) position.''' If the device ever
  shows the Petitboot screen again, that switch is the first thing to check.
* If it's stored again, label/tape the switch position so it isn't bumped.
* Consider noting the correct switch orientation physically on the case.