Troubleshooting: Boot Chain Failures

Updated

October 30, 2026

Troubleshooting: Boot Chain Failures

Diagnosing boot failures requires isolating which phase of the boot chain experienced the breakdown:

  Firmware (UEFI)   -->   Bootloader (GRUB)   -->   Initramfs (/init)   -->   PID 1 (Init)
        |                        |                         |                      |
[No bootable device]      [GRUB rescue shell]        [Kernel panic VFS]     [Frozen screen]

Phase 1: Firmware / Bootloader Errors

“No bootable device found” or dropping into UEFI Shell

  • Root Cause: The ESP partition does not exist, is formatted as NTFS/ext4 instead of FAT32, or the file /EFI/BOOT/BOOTX64.EFI is missing.
  • Diagnostic: In the UEFI shell, type fs0: followed by ls EFI\BOOT to confirm the presence of the EFI binary.

grub rescue> error: unknown filesystem

  • Root Cause: GRUB’s Stage 1 booted from the MBR/ESP, but it cannot read the partition containing /boot/grub because the filesystem module (ext2.mod, btrfs.mod) is not accessible.

  • Remedy from Rescue Shell:

    grub rescue> ls
(hd0) (hd0,gpt1) (hd0,gpt2)
grub rescue> ls (hd0,gpt2)/
grub rescue> set root=(hd0,gpt2)
grub rescue> set prefix=(hd0,gpt2)/boot/grub
grub rescue> insmod normal
grub rescue> normal

Phase 2: Initramfs & Switch Root Failures

Dropping into the Emergency Rescue Shell

If your /init script contains exec /bin/sh on error, you will see a rescue prompt:

[initramfs] FATAL: Failed to mount root filesystem!
/bin/sh: can't access tty; job control turned off
#

Diagnostic Steps: 1. Check available block devices: sh # cat /proc/partitions # ls -l /dev/sd* /dev/nvme* /dev/vd* 2. Manually test mounting: sh # mount /dev/vda2 /newroot 3. If /dev/vda2 does not exist: the storage driver module was not loaded. Verify whether modprobe virtio_blk or ahci succeeds.

switch_root: bad newroot /newroot

  • Root Cause: switch_root has strict POSIX safety checks:
    1. /newroot must be an active mount point (not just a plain directory).
    2. The target binary (/newroot/sbin/init) must exist and have executable permissions.
    3. The current root must be a tmpfs or ramfs (which initramfs is).
  • Remedy: Ensure your init script successfully mounts the root filesystem before invoking switch_root.

Debugging Flags for the Bootloader

When booting, press e in GRUB to edit the kernel command line: - Remove quiet and splash. - Add rd.debug (for dracut) or debug. - Add init=/bin/sh to bypass all init systems and boot directly into a root shell.