From 1f7bb7961d058822a4975f6fac3ed2365e56a9d2 Mon Sep 17 00:00:00 2001
From: parulin <161326115+parulin@users.noreply.github.com>
Date: Tue, 30 Sep 2025 09:00:45 -0400
Subject: [PATCH] Add a warning for outdated grub.cfg file

---
 user/troubleshooting/uefi-troubleshooting.rst | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/user/troubleshooting/uefi-troubleshooting.rst b/user/troubleshooting/uefi-troubleshooting.rst
index bfacaeea..fb780f1c 100644
--- a/user/troubleshooting/uefi-troubleshooting.rst
+++ b/user/troubleshooting/uefi-troubleshooting.rst
@@ -148,3 +148,25 @@ Accessing installer Rescue mode on UEFI
 ---------------------------------------
 
 Choose “Rescue a Qubes OS system” from grub2 boot menu.
+
+Updating GRUB options doesn't work
+----------------------------------
+
+If you upgraded from Qubes OS R4.0 or followed outdated instructions, you might have a wrong `grub.cfg` file.
+
+The content of :file:`/boot/efi/EFI/qubes/grub.cfg` should be something like:
+
+.. code:: bash
+
+   search --no-floppy --fs-uuid --set=dev xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+   set prefix=($dev)/grub2
+   export $prefix
+   configfile $prefix/grub.cfg
+
+Where the end of the first line is replaced by a UUID. If not, you can reinstall this file:
+
+.. code:: console
+
+   sudo qubes-dom0-update --action=reinstall grub2-common
+
+After that, running the `grub2-mkconfig` command should work.