Troubleshooting: ISO and Installation Issues

Updated

October 30, 2026

Troubleshooting: ISO and Installation Issues

Creating bootable ISO images is fraught with edge cases across different motherboard vendors and firmware versions.

1. ISO Boots on BIOS but Freezes on UEFI

Symptom: The ISO boots perfectly inside legacy BIOS virtual machines, but modern UEFI hardware reports:

Secure Boot Violation: Invalid Signature Detected
- or -
Drops immediately into the EFI Shell: Shell>

Root Cause: 1. The El Torito alternative boot catalog was missing the -isohybrid-gpt-basdat parameter during xorriso execution. 2. The FAT filesystem image containing /EFI/BOOT/BOOTX64.EFI was formatted incorrectly or corrupted.

Diagnostic Check: Inspect the generated ISO with fdisk:

$ fdisk -l byol-installer-x86_64.iso
Device                       Boot Start     End Sectors  Size Id Type
byol-installer-x86_64.iso1   *        0 4194303 4194304    2G  0 Empty
byol-installer-x86_64.iso2         1024   10239    9216  4.5M ef EFI (FAT-12/16/32)

If partition 2 with type ef EFI does not appear in the partition table, UEFI motherboards will refuse to boot it from a USB drive!

2. Kernel Boots but Initramfs Fails to Find Installation Media

Symptom: The kernel loads, prints driver logs, and then halts:

[initramfs] Searching for installation media with label 'BYOL_LIVE'...
[initramfs] ERROR: Installation device not found!
/bin/sh: can't access tty; job control turned off
#

Root Cause: - USB 3.0 controller drivers (xhci_pci, xhci_hcd) take several hundred milliseconds to detect plugged-in storage devices after the kernel initializes. If your /init script checks for the disk immediately, the device node has not been populated yet! - The filesystem label set during xorriso -volid was BYOL_LIVE, but your /init script looked for BYOL_ISO or byol_live (case-sensitive mismatch).

Remedy: Add an explicit settling loop in /init:

echo "[initramfs] Waiting for storage devices to settle..."
for i in 1 2 3 4 5; do
    DEV=$(blkid -L "BYOL_LIVE" || true)
    if [ -n "$DEV" ]; then
        echo "[initramfs] Found installation media at $DEV"
        mount -t iso9660 -o ro "$DEV" /mnt/cdrom
        break
    fi
    sleep 1
done

3. Windows dd / Rufus Corrupting Hybrid ISOs

When users write an ISO to USB on Windows using tools like Rufus: - Advise users to select “Write in DD Image mode” rather than “ISO Image mode”. - Writing in ISO Image mode attempts to unpack the ISO into FAT32, altering directory structures and breaking symlinks. Writing in DD mode performs an exact sector-by-sector clone, preserving hybrid MBR/GPT structures.