A broken
grub.cfg prevents Linux from booting by removing valid kernel parameters or OS entries. The most reliable fix is to regenerate this file using the
update-grub command, which scans your system for installed operating systems and rebuilds the configuration automatically. If you cannot reach a terminal, booting from a live USB allows you to mount your partitions and run the repair commands manually. This process restores the GRUB bootloader’s ability to locate kernels and initrd images, resolving black screen or "file not found" errors during startup.
Understanding the Role of grub.cfg
The
grub.cfg file is the central configuration script that the GRand Unified Bootloader (GRUB) reads every time you start your computer. It tells the bootloader where to find the Linux kernel, the initial ramdisk (
initrd), and any other operating systems like Windows on your machine. When this file becomes corrupted—often due to incomplete updates, manual editing errors, or disk failures—GRUB loses its roadmap. Instead of displaying a menu, the system may drop into a
grub> prompt or display an error message stating that the required files are missing.
Regenerating this file is generally safe because modern tools do not delete existing data; they simply overwrite the configuration with fresh, accurate information derived from your current system state. However, it is crucial to understand that
grub.cfg is typically generated dynamically rather than edited by hand. Directly modifying this file is discouraged because any subsequent system update will likely overwrite your changes, leading to further confusion.
Fixing via Live USB Method
When your primary operating system fails to boot entirely, you must use a Live USB environment to access the necessary repair tools. This method works for almost all Debian-based distributions (like Ubuntu, Linux Mint, and Kali) and many others.
First, create a bootable USB drive using your preferred Linux distribution’s ISO image. Insert the USB into your computer and restart it. Enter the BIOS or UEFI settings by pressing the appropriate key (commonly F2, F12, Del, or Esc) during startup. Change the boot order to prioritize the USB drive and save your changes. Once the system boots into the Live environment, open a terminal window.
You need to identify which partition contains your root Linux installation. Run the following command to list available block devices:
lsblk
Look for the partition that matches the size of your main hard drive and is labeled as
ext4 or
btrfs. Let us assume this is
/dev/sda2 for the sake of this guide. You must mount this partition to a temporary directory so the repair tool can see it. Execute these commands:
sudo mount /dev/sda2 /mnt
If you have a separate EFI System Partition (ESP), you must mount it as well. This is usually a small FAT32 partition, often
/dev/sda1. Create a mount point and attach it:
sudo mkdir -p /mnt/boot/efi
sudo mount /dev/sda1 /mnt/boot/efi
In some cases, if you have a separate
/boot partition, you should mount that too. For most standard setups, mounting the root and EFI partitions is sufficient. Now, you need to bind the virtual filesystems so that the chroot environment has access to device nodes and temporary files. Run:
sudo mount --bind /dev /mnt/dev
sudo mount --bind /proc /mnt/proc
sudo mount --bind /sys /mnt/sys
Now, change root into your mounted system:
sudo chroot /mnt
Once inside the chroot environment, you are effectively running as if you were logged into your broken system. The final step is to regenerate the GRUB configuration. For Debian-based systems, use:
update-grub
For Red Hat-based systems (like Fedora or CentOS), the command might differ slightly, often involving
grub2-mkconfig -o /boot/grub2/grub.cfg. After the command completes successfully without errors, exit the chroot environment:
exit
Then unmount the partitions in reverse order:
sudo umount /mnt/dev
sudo umount /mnt/proc
sudo umount /mnt/sys
sudo umount /mnt/boot/efi
sudo umount /mnt
Remove the USB drive and reboot your computer. Your GRUB menu should now appear with all your operating systems listed correctly.
Repairing from the GRUB Command Line
Sometimes, you may be stuck at the
grub> prompt but still have access to basic commands. This situation occurs when the configuration file is missing entirely, but the underlying files remain intact. You can manually boot into your system to gain access and then run the repair commands.
At the
grub> prompt, you need to set the root device to your Linux partition. Use the
ls command to list available drives:
ls
This will output something like
(hd0,gpt1),
(hd0,gpt2), etc. Identify the partition containing your
/boot directory. Set it as the root:
set root=(hd0,gpt2)
Next, specify the kernel path. Assuming your kernel is located in the root of the partition:
linux /vmlinuz root=/dev/sda2 ro
Replace
/dev/sda2 with the actual device name of your root partition. Then, load the initial ramdisk:
initrd /initrd.img
Finally, boot the system:
boot
If successful, you will boot into your Linux desktop. Immediately open a terminal and run
sudo update-grub (or the equivalent for your distro) to permanently fix the issue. This method is a temporary workaround to regain access; you must still run the regeneration command to ensure future boots work automatically.
Common Pitfalls and Verification
After regenerating
grub.cfg, verify that the file contains entries for all your installed operating systems. Open the file with a text editor:
sudo nano /boot/grub/grub.cfg
Scroll through the file and look for
menuentry blocks. Each installed OS should have its own entry. If Windows is missing, check that the
os-prober package is installed and enabled. On newer GRUB versions,
os-prober is disabled by default for security reasons. To enable it, edit
/etc/default/grub and add the line
GRUB_DISABLE_OS_PROBER=false, then run
update-grub again.
Another common issue arises with UEFI systems where the EFI partition is not mounted correctly during the chroot process. If you forget to mount the EFI partition, the new
grub.cfg might not be written to the correct location, or the bootloader binaries might not be updated properly. Always double-check your mount points before running
update-grub.
For users dealing with complex dual-boot setups involving GPT and EFI system partitions, ensuring the correct partition alignment is vital. If you encounter persistent issues after following these steps, consider reviewing how the boot menu presents itself in specific UEFI environments. You can refer to our guide on
How is the grub boot menu presented if the gpt looks for efi system partition for deeper insights into EFI partition structures. Additionally, if you are trying to restore access to older Windows installations that disappeared from the menu, the techniques used to reconstruct EFI files may provide additional context. See
How to Reconstruct EFI File to Make Windows 7 Reappear on GRUB for those specific scenarios.
Frequently Asked Questions
Will updating GRUB delete my personal files?
No, regenerating
grub.cfg only modifies the bootloader configuration file. It does not touch your home directory, documents, or installed applications. The operation is strictly limited to the
/boot and
/boot/grub directories.
What if update-grub says "command not found"?
This indicates you are likely using a non-Debian-based distribution such as Fedora, Arch, or openSUSE. These systems use different package managers and commands. For example, Fedora uses
grub2-mkconfig. Check your distribution’s documentation for the specific command to regenerate GRUB configuration.
Can I manually edit grub.cfg instead of regenerating it?
While technically possible, it is strongly discouraged. Manual edits are fragile and will be overwritten by any future kernel updates or system upgrades. Using
update-grub ensures that your configuration remains consistent with the currently installed kernels and modules.
Why does Windows disappear from the GRUB menu after an update?
Modern Linux distributions disable
os-prober by default to prevent potential security vulnerabilities associated with scanning other partitions. If Windows vanishes, you likely need to enable
os-prober in
/etc/default/grub and run
update-grub again to rescan for other operating systems.
Is it safe to run these commands on a RAID setup?
Yes, provided you identify the correct logical volume device (e.g.,
/dev/md0 or
/dev/mapper/cryptroot) when mounting your root partition. The
update-grub command handles software RAID configurations automatically as long as the underlying devices are accessible within the chroot environment.