Docs: Troubleshooting

AcornOS documentation

Troubleshooting

Common issues and solutions for AcornOS installation and usage.

Install Issues

recpart refuses the disk

It prints the check that failed, an error code and what to do. --dry-run runs the same checks without changing anything.

Show the steps and anything apply would refuse
recpart apply --disk /dev/nvme0n1 --dry-run

Boot Issues

System fails to boot

Boot from the ISO again and check the installed boot files:

Mount root A, the EFI partition and the state partition
mount /dev/nvme0n1p2 /mnt
mount /dev/nvme0n1p1 /mnt/boot
mount /dev/nvme0n1p4 /mnt/var
Check that both root entries and root A's kernel are on the EFI partition
ls /mnt/boot/loader/entries
ls /mnt/boot/acornos-a

You should see acornos-a.conf and acornos-b.conf, and vmlinuz and initramfs.img for root A. Each entry's options line names its root by root=PARTUUID=; compare it with blkid -s PARTUUID /dev/nvme0n1p2.

Reinstall systemd-boot and the A/B boot layout
recsetup apply --root /mnt --boot ab --slot-a /dev/nvme0n1p2 --slot-b /dev/nvme0n1p3 --machine-id && recab verify-installation --root /mnt

Bootloader not found (UEFI)

Ensure you booted in UEFI mode and the ESP is mounted correctly:

Check if EFI variables are accessible
ls /sys/firmware/efi/efivars
Verify ESP is mounted at /boot
findmnt /boot

The other root did not start

The boot default is the root that last finished starting. When the other root does not finish starting, the next boot starts the previous root again. recab status shows which root is booted, which is the other and what boots next; recab health shows how startup ended. To start over from the running system, run recab copy: it overwrites the other root with a copy of the booted root.

Show the booted root, the other root and what boots next
recab status

Network Issues

No network after reboot

Check the interfaces and their addresses
ip addr
Check that networkmanager runs
rc-service networkmanager status
Start it now and at every boot
doas rc-update add networkmanager default
doas rc-service networkmanager start

WiFi adapter not detected

List wireless devices
nmcli device wifi list

If no wireless device appears, the card may need firmware the system does not ship.

Package Issues

Package installation fails

Recipe reports the failure and names the failing step. See what it holds and which step is done:

See the state of the program
doas recipe state packagename

Inspect recipe explain packagename: downloads need every server and redirect target in the recipe's NEEDS.network. Caller --network-host and --no-network can only restrict it. The full log of every run is under /var/lib/recipe/state/logs/.

Retry from scratch: clean up the program, then install again
doas recipe cleanup packagename
doas recipe install packagename