RTFM · Troubleshooting

Boot failures

Nothing on screen, kernel panic, initramfs prompt, or dropped into emergency shell: separating bootloader problems from kernel problems from userspace problems.

Name the stage where it stops

Boot stages and their failure signatures
Stage reached	Typical symptom	Suspect
Firmware POST	No video, beep codes	Hardware
GRUB menu	Stuck at grub rescue>	GRUB config / disk visibility
Kernel load	'Loading Linux' then freeze	Corrupt kernel/initramfs
Early userspace	initramfs emergency shell	root= argument, missing modules
Init	panic: no init found	Root filesystem corruption
OpenRC	services cascade-stopping at boot	Per-service issues

GRUB rescue prompt

You can boot manually from rescue> even with broken config, proving where the fault lies.

Manual boot from rescue prompt

grub> ls                                # discover disks
grub> set root=(hd0,gpt2)
grub> linux /boot/vmlinuz-7.2.0-akadata root=/dev/sda2
grub> initrd /boot/initramfs-image
grub> boot

initramfs emergency shell

The initramfs could not find or mount root. Check the root= parameter matches stable identifiers; enumeration order changes when disks move.

Root specified by /dev/sdaX breaks when a USB stick shifts enumeration. Prefer UUID= values reported by blkid.

Identify root stably

blkid                 # find UUID

Recovery from outside

When local console is unusable, boot rescue media, mount the target root, chroot in, and rebuild.

Chroot recovery recipe

# From rescue media
mount /dev/sda2 /mnt
mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys
chroot /mnt
# repair, then:
grub-mkconfig -o /boot/grub/grub.cfg

Prove it works: repeatable boot

machine boots unattended twice consecutively with identical configuration; flaky boots count as failed boots.

Kernel-specific failures

Did we miss something?

If this page left something unanswered, found an error, or there is another subject you would like documented, tell us. Saphira’s documentation grows from real problems people need to solve.

Send feedback or request a new section →

Prefer not to do it yourself?

Everything needed to do the work yourself is documented here and remains free — we charge for human time, not for withholding knowledge. Sometimes the missing resource is simply time. The same people who build Saphira can provide paid professional help with implementation, migration, troubleshooting and administration.

Ask about professional support →