GRUB/Troubleshooting

This article documents issues that might arise when trying to use or install GRUB2.

Installation errors

Installing GRUB2 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 GRUB2 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 efivars

root #emerge --ask sys-boot/efibootmgr

Next 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.

Note
The following examples presumes a 64-bit EFI GRUB2 install, adjust accordingly for 32-bit EFI.

root #grub-install --target=x86_64-efi

grub-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 GRUB2 using the following command:

root #emerge --ask --newuse sys-boot/grub:2

In 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=/boot

grub-install: Attempting to install GRUB2 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 /boot

No 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 GRUB2 in a partition

When attempting to install GRUB2 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.

Note
This is true for GRUB version 1.99x only... for GRUB2 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-setup

grub-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 GRUB2 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/sda

grub-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 (Gentoo-based) 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.