> ## Documentation Index
> Fetch the complete documentation index at: https://docs.derekdinh.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Linux Boot Repair: GRUB Errors and Filesystem Issues

> Fix Linux systems that fail to boot due to GRUB errors, corrupted filesystems, or bad kernel parameters using recovery mode and command-line tools.

A Linux system that refuses to boot almost always shows its hand through error messages at the GRUB stage or during kernel initialization. Whether you are facing a blank GRUB prompt, a "file not found" error, or a filesystem that fails to mount at startup, the tools to diagnose and repair the problem are available directly from the boot environment — no external media required in most cases.

## Understanding the Linux Boot Sequence

Before applying fixes, it helps to know where in the sequence the failure is occurring:

<AccordionGroup>
  <Accordion title="Stage 1: Firmware (BIOS/UEFI)">
    The firmware initializes hardware and hands off to the bootloader. If you see no output at all, or the firmware reports no bootable device, the issue is at this stage — check UEFI boot order settings.
  </Accordion>

  <Accordion title="Stage 2: GRUB bootloader">
    GRUB loads the kernel and initramfs. Errors here appear as `error: file '/boot/grub/grub.cfg' not found`, `unknown filesystem`, or a bare `grub>` prompt. GRUB reinstallation resolves most of these.
  </Accordion>

  <Accordion title="Stage 3: Kernel and initramfs">
    The kernel mounts a temporary root filesystem (initramfs) and starts the device detection process. Kernel panic messages at this stage often point to a missing driver or a corrupted initramfs image.
  </Accordion>

  <Accordion title="Stage 4: init / systemd">
    The real root filesystem is mounted and systemd starts services. Failures here produce journal errors and often drop you to an emergency shell. Run `journalctl -xb` to read the log.
  </Accordion>
</AccordionGroup>

***

## Step-by-Step Boot Repair

<Steps>
  <Step title="Read the Error Message and Access the GRUB Menu">
    When the system fails to boot, the first action is to capture the exact error text — it directly determines which repair path to follow.

    * If the machine reboots immediately without displaying anything, press **Esc** or **Shift** (BIOS systems) during POST to hold the GRUB menu open.
    * On UEFI systems, hold **Shift** immediately after the firmware logo disappears.

    From the GRUB menu you can:

    * **Edit a boot entry** by pressing **E** — useful for adding temporary kernel parameters.
    * **Drop to the GRUB shell** by pressing **C** — useful for manually specifying a boot path.

    ```bash theme={null}
    # From the GRUB shell, list detected drives and partitions:
    grub> ls

    # List the contents of a partition to confirm it's your /boot:
    grub> ls (hd0,gpt2)/

    # Manually boot a known-good kernel (adjust partition and kernel version):
    grub> set root=(hd0,gpt2)
    grub> linux /vmlinuz-6.5.0-generic root=/dev/sda3 ro
    grub> initrd /initrd.img-6.5.0-generic
    grub> boot
    ```

    <Tip>
      Use Tab completion inside the GRUB shell to discover available partition names and kernel filenames without needing to memorize them.
    </Tip>
  </Step>

  <Step title="Boot into Recovery Mode">
    Most Debian/Ubuntu-based distributions include a **recovery mode** entry in the GRUB menu that drops you to a root shell with minimal services running.

    1. At the GRUB menu, select the entry labelled **"Advanced options for Ubuntu"** (or your distribution's equivalent).
    2. Select the **recovery mode** entry for the most recent kernel version.
    3. From the recovery menu, choose **"Drop to root shell prompt"** and press Enter.
    4. Remount the filesystem as read-write before making any changes:

    ```bash theme={null}
    mount -o remount,rw /
    ```

    <Note>
      On systems using systemd, if you are dropped to an **emergency shell** automatically, the filesystem is likely already mounted read-only. Always run the `remount` command above before attempting repairs.
    </Note>

    For distributions without a recovery menu (e.g., Arch, Fedora), append `systemd.unit=rescue.target` to the kernel command line in the GRUB editor (press **E** at the GRUB menu).

    ```bash theme={null}
    # Example kernel line with rescue target appended:
    linux /vmlinuz-linux root=/dev/sda2 ro quiet systemd.unit=rescue.target
    ```
  </Step>

  <Step title="Check and Repair a Corrupted Filesystem with fsck">
    `fsck` (filesystem consistency check) scans and repairs ext4, xfs, and other Linux filesystems. It **must** be run on an unmounted or read-only filesystem.

    1. Identify the device name of your root partition:

    ```bash theme={null}
    lsblk -f
    # Look for your root (/) mount point — commonly /dev/sda1, /dev/nvme0n1p2, etc.
    ```

    2. Unmount or remount the partition read-only:

    ```bash theme={null}
    # If the filesystem is currently mounted rw, remount it ro:
    mount -o remount,ro /dev/sda1

    # Or, if booted from a live USB, unmount it entirely:
    umount /dev/sda1
    ```

    3. Run fsck with automatic repair enabled:

    ```bash theme={null}
    # For ext4 filesystems (-y automatically answers "yes" to all repair prompts):
    fsck -y /dev/sda1

    # For a more verbose pass-by-pass report:
    fsck -yv /dev/sda1

    # Force a check even if the filesystem appears clean:
    fsck -yf /dev/sda1
    ```

    <Warning>
      Never run `fsck` on a mounted read-write filesystem — doing so will corrupt it further. If you cannot unmount the root partition from within the running system, boot from a live USB/CD instead.
    </Warning>

    4. If fsck reports **"UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY"**, run it a second time on the unmounted device. Multiple passes are sometimes required for severely damaged filesystems.

    5. After a clean fsck run, reboot:

    ```bash theme={null}
    reboot
    ```
  </Step>

  <Step title="Reinstall GRUB to Fix a Broken Bootloader">
    If GRUB's core image or configuration files are missing or corrupted, you need to reinstall GRUB from a working environment. The most reliable method uses a live USB.

    **Preparation: Boot from a Live USB**

    Boot your distribution's live ISO (Ubuntu, Debian, etc.) and open a terminal.

    **1. Identify your disk layout:**

    ```bash theme={null}
    lsblk
    # Identify your root partition (e.g., /dev/sda2) and
    # EFI System Partition if on UEFI (e.g., /dev/sda1, type vfat)
    ```

    **2. Mount the installed system:**

    ```bash theme={null}
    # Mount root partition:
    sudo mount /dev/sda2 /mnt

    # Mount EFI partition (UEFI systems only):
    sudo mount /dev/sda1 /mnt/boot/efi

    # Bind-mount virtual filesystems:
    sudo mount --bind /dev  /mnt/dev
    sudo mount --bind /proc /mnt/proc
    sudo mount --bind /sys  /mnt/sys
    ```

    **3. Chroot into the installed system:**

    ```bash theme={null}
    sudo chroot /mnt
    ```

    **4. Reinstall GRUB:**

    <Tabs>
      <Tab title="BIOS / Legacy Systems">
        ```bash theme={null}
        # Install GRUB to the MBR of the primary disk:
        grub-install /dev/sda

        # Regenerate the GRUB configuration file:
        update-grub
        ```
      </Tab>

      <Tab title="UEFI Systems">
        ```bash theme={null}
        # Install GRUB for EFI (adjust --efi-directory if your EFI partition
        # is mounted elsewhere):
        grub-install --target=x86_64-efi \
                     --efi-directory=/boot/efi \
                     --bootloader-id=ubuntu \
                     --recheck

        # Regenerate GRUB config:
        update-grub
        ```
      </Tab>

      <Tab title="Fedora / RHEL (grub2)">
        ```bash theme={null}
        # BIOS:
        grub2-install /dev/sda
        grub2-mkconfig -o /boot/grub2/grub.cfg

        # UEFI:
        grub2-install --target=x86_64-efi \
                      --efi-directory=/boot/efi \
                      --bootloader-id=fedora
        grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg
        ```
      </Tab>
    </Tabs>

    **5. Exit the chroot and reboot:**

    ```bash theme={null}
    exit
    sudo umount -R /mnt
    sudo reboot
    ```

    <Note>
      If `update-grub` reports "Warning: os-prober will not be executed", and you have other operating systems on the disk, add `GRUB_DISABLE_OS_PROBER=false` to `/etc/default/grub` and rerun `update-grub`.
    </Note>
  </Step>

  <Step title="Edit GRUB Configuration and Kernel Parameters">
    Persistent kernel boot parameters — such as disabling a problematic driver, forcing a specific root device, or enabling verbose logging — are managed through the GRUB default configuration file.

    **Temporary change (single boot):**

    Press **E** at the GRUB menu to edit the boot entry. Find the line beginning with `linux` and append your parameters after `quiet splash`. Press **Ctrl+X** or **F10** to boot.

    ```bash theme={null}
    # Common temporary parameters to add:
    # nomodeset          — disable kernel mode setting (fixes blank screen with some GPUs)
    # ro single          — boot to single-user mode for maintenance
    # systemd.unit=emergency.target  — drop to emergency shell immediately
    # acpi=off           — disable ACPI (workaround for some hardware issues)
    ```

    **Permanent change:**

    ```bash theme={null}
    # Edit the GRUB defaults file:
    sudo nano /etc/default/grub

    # Locate the GRUB_CMDLINE_LINUX_DEFAULT line and add your parameter:
    # Before: GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"
    # After:  GRUB_CMDLINE_LINUX_DEFAULT="quiet splash nomodeset"

    # Save the file, then regenerate grub.cfg:
    sudo update-grub
    # or on RHEL/Fedora:
    sudo grub2-mkconfig -o /boot/grub2/grub.cfg
    ```

    <Warning>
      Do not manually edit `/boot/grub/grub.cfg` — it is auto-generated and your changes will be overwritten the next time `update-grub` runs. Always make persistent changes in `/etc/default/grub`.
    </Warning>

    **Verify the active kernel command line after booting:**

    ```bash theme={null}
    cat /proc/cmdline
    ```
  </Step>

  <Step title="Rebuild the initramfs Image">
    If the kernel loads but panics before mounting the root filesystem, the initramfs (initial RAM filesystem) image may be missing or corrupted. Rebuild it from recovery mode or a chroot environment.

    ```bash theme={null}
    # Debian / Ubuntu:
    sudo update-initramfs -u -k all

    # Fedora / RHEL:
    sudo dracut --force --regenerate-all

    # Arch Linux:
    sudo mkinitcpio -P

    # Verify the image was created (adjust kernel version as needed):
    ls -lh /boot/initrd.img-*
    ```

    After rebuilding, rerun `update-grub` (or the equivalent) to ensure GRUB's config points to the new image, then reboot.
  </Step>
</Steps>

***

## Escalation

<AccordionGroup>
  <Accordion title="When fsck cannot repair the filesystem">
    If fsck completes but reports unrepairable errors, the underlying storage device may have bad sectors. Run a SMART diagnostic to assess drive health:

    ```bash theme={null}
    sudo apt install smartmontools   # Debian/Ubuntu
    sudo smartctl -a /dev/sda
    ```

    A `FAILED` SMART status or a high count of reallocated sectors indicates the drive needs replacement before data can be trusted.
  </Accordion>

  <Accordion title="GRUB reinstall succeeds but system still won't boot">
    Boot back into the live environment and check whether the initramfs image exists and is non-zero in size (`ls -lh /mnt/boot/`). A missing or zero-byte initramfs is a common cause of post-GRUB kernel panics. Rebuild it as shown in Step 6.
  </Accordion>

  <Accordion title="Escalation path">
    1. Save the full output of `journalctl -xb` and `dmesg` to a USB drive for review.
    2. Document the exact GRUB error message and all repair steps attempted.
    3. Submit a detailed ticket to your Linux systems administrator or IT helpdesk, including the distribution version (`cat /etc/os-release`), kernel version (`uname -r`), and disk layout (`lsblk -f`).
  </Accordion>
</AccordionGroup>