22 Error messages produced by GRUB
**********************************

22.1 GRUB only offers a rescue shell
====================================

GRUB's normal start-up procedure involves setting the 'prefix'
environment variable to a value set in the core image by 'grub-install',
setting the 'root' variable to match, loading the 'normal' module from
the prefix, and running the 'normal' command (*note normal::).  This
command is responsible for reading '/boot/grub/grub.cfg', running the
menu, and doing all the useful things GRUB is supposed to do.

   If, instead, you only get a rescue shell, this usually means that
GRUB failed to load the 'normal' module for some reason.  It may be
possible to work around this temporarily: for instance, if the reason
for the failure is that 'prefix' is wrong (perhaps it refers to the
wrong device, or perhaps the path to '/boot/grub' was not correctly made
relative to the device), then you can correct this and enter normal mode
manually:

     # Inspect the current prefix (and other preset variables):
     set
     # Find out which devices are available:
     ls
     # Set to the correct value, which might be something like this:
     set prefix=(hd0,1)/grub
     set root=(hd0,1)
     insmod normal
     normal

   However, any problem that leaves you in the rescue shell probably
means that GRUB was not correctly installed.  It may be more useful to
try to reinstall it properly using 'grub-install DEVICE' (*note Invoking
grub-install::).  When doing this, there are a few things to remember:

   * Drive ordering in your operating system may not be the same as the
     boot drive ordering used by your firmware.  Do not assume that your
     first hard drive (e.g.  '/dev/sda') is the one that your firmware
     will boot from.  'device.map' (*note Device map::) can be used to
     override this, but it is usually better to use UUIDs or file system
     labels and avoid depending on drive ordering entirely.

   * At least on BIOS systems, if you tell 'grub-install' to install
     GRUB to a partition but GRUB has already been installed in the
     master boot record, then the GRUB installation in the partition
     will be ignored.

   * If possible, it is generally best to avoid installing GRUB to a
     partition (unless it is a special partition for the use of GRUB
     alone, such as the BIOS Boot Partition used on GPT). Doing this
     means that GRUB may stop being able to read its core image due to a
     file system moving blocks around, such as while defragmenting,
     running checks, or even during normal operation.  Installing to the
     whole disk device is normally more robust.

   * Check that GRUB actually knows how to read from the device and file
     system containing '/boot/grub'.  It will not be able to read from
     encrypted devices with unsupported encryption scheme, nor from file
     systems for which support has not yet been added to GRUB.

22.2 Firmware stalls instead of booting GRUB
============================================

The EFI implementation of some older MacBook laptops stalls when it gets
presented a grub-mkrescue ISO image for x86_64-efi target on an USB
stick.  Affected are models of year 2010 or earlier.  Workaround is to
zeroize the bytes 446 to 461 of the EFI partition, where mformat has put
a partition table entry which claims partition start at block 0.  This
change will not hamper bootability on other machines.