TrueNAS stuck at GRUB command line? Try this recovery guide

TrueNAS General
1

If you restart TrueNAS and it only loads into the GRUB terminal with no boot menu, the normal advice is to reinstall the OS and restore your configuration backup.
But if you’ve lost your backup, it’s out of date, or you can only access the server via remote console/KVM without OS install media, you may still be able to boot.

This guide is for cases where:

  • The boot drive is intact (no major corruption or hardware failure).
  • TrueNAS was running fine before reboot.
  • GRUB itself is failing to load the menu.

If the boot device is dead or the pool is badly damaged, this won’t work.

Manual Boot Steps

GRUB behaves differently on different hardware, but these steps are generic enough to work in most cases.

  1. Check if the all_video module is available: echo $feature_all_video_module If the output is y, go to step 2. Otherwise, go to step 3.

  2. Load all video modules at once: insmod all_video Then go to step 4.

  3. Load video modules individually:
    insmod efi_gop
    insmod efi_uga
    insmod ieee1275_fb
    insmod vbe
    insmod vga
    insmod video_bochs
    insmod video_cirrus
    Then go to step 4.

  4. Load compression and filesystem modules:
    insmod gzio
    if [ x$grub_platform = xxen ]; then insmod xzio; insmod lzopio; fi
    insmod part_gpt
    insmod zfs

  5. Identify the boot-pool’s disk and UUID: ls (hd0)
    Check each (hdX) until you find:

  • A small EFI partition (FAT)
  • A ZFS partition labeled boot-pool
    Example:
    Partition hd0,gpt3: Filesystem type zfs - Label 'boot-pool' - UUID 0123456789abcdef

  1. Set the root device: search --no-floppy --fs-uuid --set=root <UUID>

  2. Find the boot environment name (BE name). Usually it’s the TrueNAS version. Use that to find the kernel and initrd files: ls /ROOT/<BE NAME>@/boot/

  3. Load the kernel: linux /ROOT/<BE NAME>@/boot/vmlinuz-6.12.15-production+truenas root=ZFS=boot-pool/ROOT/<BE NAME> ro libata.allow_tpm=1 amd_iommu=on iommu=pt kvm_amd.npt=1 kvm_amd.avic=1 intel_iommu=on zfsforce=1 nvme_core.multipath=N
    Replace with your actual vmlinuz filename.

  4. Load the initrd: initrd /ROOT/<BE NAME>@/boot/initrd.img-6.12.15-production+truenas
    Replace with your actual initrd filename.

  5. Boot: boot

After Booting Successfully

  1. Immediately export your TrueNAS configuration.

  2. Run a scrub of the boot-pool: zpool scrub boot-pool
    Reboot afterwards. If it boots normally, GRUB’s issue may have been minor ZFS metadata damage that’s now fixed.

  3. If it still fails, repeat the manual boot, then as root:
    update-grub
    grub-install /dev/<boot-device>
    Replace <boot-device> with your actual boot device. Reboot again.

  4. If it still doesn’t boot, reinstall TrueNAS and restore your configuration.

I hope this helps.