GRUB/Troubleshooting
This article documents issues that might arise when trying to use or install GRUB.
Installation errors
Installing GRUB from within a chroot
When a separate /boot partition exists, be sure to mount the target root partition before chrooting, but do not mount the /boot partition until after chrooting to the new environment. This is required because grub-mkconfig will not detect /boot as a separate partition and will assume the /boot directory and the root (/) directory are on the same partition.
Reinstalling the GRUB EFI boot manager entry
In case the boot manager entries need to be restored, they can be re-added without invoking grub-install. Load the efivars kernel module and install sys-boot/efibootmgr:
root #modprobe efivarsroot #emerge --ask sys-boot/efibootmgrNext add a boot menu entry:
root #efibootmgr --create --gpt --disk /dev/sda --part 1 --write-signature --label "gentoo" --loader "\\EFI\\gentoo\\grubx86.efi"grub-install: error: cannot find EFI directory.
The following examples presumes a 64-bit EFI GRUB install, adjust accordingly for 32-bit EFI.
root #grub-install --target=x86_64-efigrub-install: error: cannot find EFI directory.
Properly setting the GRUB_PLATFORMS variable in /etc/portage/make.conf (the first time!) as listed above should resolve this error. Set the GRUB_PLATFORMS variable then re-emerge GRUB using the following command:
root #emerge --ask --newuse sys-boot/grub:2In the case this error persists try forcing the install to the EFI directory by issuing the grub-install command with correct parameters for the --target and --efi-directory options:
root #grub-install --target=x86_64-efi --efi-directory=/bootgrub-install: Attempting to install GRUB to a disk or partition
root #grub-install /dev/sda1 Attempting to install GRUB to a partition disk or to a partition. This is a BAD idea. Embedding is not possible. GRUB can only be installed in this setup by using blocklists. However, blocklists are UNRELIABLE and their use is discouraged.
There could be many reasons for this error to come up.
No mounted /boot
A /boot partition is not mounted.
root #mount /bootNo BIOS boot partition while using BIOS-GPT setup
This could mean there is not a EF02 or bios_boot partition to embed the core.img file in.
Creating a little partition of a few hundreds kilobytes may be enough, although it is good practice to align this partition to 2048 sectors to avoid a performance penalty with the disk. A 1 MiB partition should work well.
Attempting to install GRUB in a partition
When attempting to install GRUB in a partition e.g. /dev/sda5 (for instance because the boot loader will be chainloaded by a different boot loader), simply add --force option switch to force install.
Missing target detection
If grub-install does not print any errors message or if the error message is about scanning disk files and several platforms are enabled in /etc/portage/make.conf while nothing is installed on the disk, then edit the /sbin/grub-install script with a text editor of choice.
Change the platform variable to the appropriate platform for the current use case. The platform must be rightly set when emerging sys-boot/grub, else it will be incorrectly configured in the /sbin/grub-install script.
For example, to set the platform for "PC", change platform=qemu to platform=pc.
This is true for GRUB version 1.99x only... for GRUB the correct file to investigate can be found at /etc/grub.d/00_header; change
transform="s,grub,grub-qemu," to transform="s,grub,grub2," for instance to install rightly with grub-$platform-install.grub-setup: no post-MBR gap
root #grub-bios-setupgrub-setup: warn: This msdos-style partition label has no post-MBR gap; embedding won't be possible!
grub-bios-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists.
However, blocklists are UNRELIABLE and its use is discouraged.
grub-bios-setup: error: If you really want blocklists, use --force.
This error means that GRUB could not find the usual gap between the MBR and first partition of a disk. It is possible that the gap does not exist. Some tools (e.g. LiveUSB disk installer) format disks so that the first partition starts at sector 1 instead of 2048.
Repartitioning might be necessary to resolve the issue.
grub-install: embedding area is unusually small
root #grub-install /dev/sdagrub-install: warn: Your embedding area is unusually small. core.img won't fit in it. grub-install: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists. However, blocklists are UNRELIABLE and their use is discouraged. grub-install: error: will not proceed with blocklists.
There is not enough room at the beginning of the disk before the first partition.
In general this is a bit of trouble to fix. One or more partitions need to be resized in order to leave some free space at the beginning of the drive. The GParted LiveCD or SystemRescueCD are excellent tools to make this job less difficult.
If the swap partition is the first partition on the disk (e.g. /dev/sda1) it is possible to simply remove the existing swap space partition and re-partition the space. This resolution would avoid the need for booting into a live medium in order to resize a root (/) partition.
Boot errors
Troubleshooting steps in this section presume GRUB has been installed correctly, but issues are encountered when booting the operating system.
error: no such device
This error occurs when GRUB cannot detect a device for which to boot. This can occur for one or many of the following reasons:
- Physical issues
- The device has been intentionally removed/disconnected from the system.
- The device has been unintentionally removed/disconnected from the system. Perhaps a power or data cable is loose or disconnected, the device has been damaged via water, impact, electrical surge, or other type of damage, the device has failed to age or end-of-life component failure.
- Logical issues
- The device is connected, but the motherboard firmware has not detected the device. A common cause is a time-of-check to time-of-use style race condition: the device itself or the bus subsystem hosting the device (PCI, SATA, USB, etc.) has not (yet) been make visible to GRUB at the time GRUB performs device detection. This results in the device not being detected. GRUB does not automatically perform a device redetection, therefore the device will not be discovered. This can be fixed by disabling fast/quick boot on via the motherboard's firmware. If disabling quick boot does not solve the problem, then it may be possible to add additional delays to the power-on self-test process so that the motherboard will give more time for all bus subsystems to initialize.
error: unknown filesystem
Unknown filesystem errors could be the result of GRUB not having the correct filesystem module inserted (loaded) at run time. This should be a result of the filesystem not being supported by the GRUB bootloader, or an issue within the grub.cfg configuration file. Generally GRUB does a good job of automatically probing filesystem when updating its configuration file.
This issue could also be a result of the device containing the filesystem not (yet) being detected by the system's firmware. See error: no such device.
booting into BIOS/EFI settings
This is typically a side effect of some GRUB updates that require a re-install.
First, chroot into the system and re-install GRUB:
For EFI systems:
root #mount /dev/sda1 /efiroot #grub-install --efi-directory=/efiOr for BIOS systems:
root #grub-install /dev/sdaNext, regenerate the config with:
root #grub-mkconfig -o /boot/grub/grub.cfgGRUB should now be fixed.