Restoring GRUB on SysLinuxOS (btrfs with subvolumes)

Recovery guide for a SysLinuxOS system that no longer boots because GRUB is corrupted, overwritten (typically after installing Windows in dual-boot), or was never installed correctly. This covers SysLinuxOS’s standard btrfs layout, with the root filesystem in the @ subvolume and @home kept separate.

When you need this

The PC shows error: no such device or drops straight into a grub> rescue shell.
No GRUB menu appears at boot; the PC jumps straight to another OS or fails outright.
Windows was installed after SysLinuxOS and overwrote the boot loader.
A kernel or GRUB update was interrupted midway.

Prerequisites

You need a bootable SysLinuxOS Live USB (MATE or Gnome build, same procedure either way). Boot the PC from the USB and open a terminal.

1. Identify the disk and subvolumes

Find the btrfs root partition and its subvolumes:

lsblk -f
sudo mount /dev/sdXN /mnt
sudo btrfs subvolume list /mnt

Look for the lines with path @ and path @home. If the disk holds more than one SysLinuxOS install (multiple @ subvolumes), check which one is the system you want to repair before continuing — for instance by inspecting /etc/hostname inside each subvolume. Then unmount the temporary mount:

sudo umount /mnt

2. Mount the right subvolume

Common mistake: mounting the partition at the top level (subvolid=5) instead of the @ subvolume. The chroot only works if you explicitly mount subvol=@:

sudo mount -o subvol=@ /dev/sdXN /mnt
sudo mount /dev/sdXM /mnt/boot/efi   # UEFI systems only, if ESP is a separate partition
sudo mount --bind /dev /mnt/dev
sudo mount --bind /proc /mnt/proc
sudo mount --bind /sys /mnt/sys

If @home lives on a separate subvolume, there’s no need to mount it for a GRUB reinstall — it isn’t touched by this procedure.

3. Enter the chroot

sudo chroot /mnt /bin/bash

From this point, commands run inside the installed system, not the Live environment.

4. Reinstall GRUB

On UEFI systems (the most common case today):

sudo grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=SysLinuxOS --recheck

On legacy BIOS systems, install onto the whole disk (MBR), never a partition:

sudo grub-install --target=i386-pc --recheck /dev/sdX

/dev/sdX is the whole disk (e.g. /dev/sda), never a partition, for legacy BIOS.

5. Regenerate the configuration

sudo update-grub

If the grub-btrfs package is installed, this step also regenerates the SysLinuxOS — snapshots submenu with the latest bootable snapshots. Confirm the command finishes without errors before leaving the chroot: an error here (e.g. a failing /etc/grub.d/ script) leaves the old grub.cfg in place and needs investigating before you reboot.

6. Exit and reboot

exit
sudo umount -R /mnt
sudo reboot

Remove the USB drive while it reboots.

Notes on multi-boot layouts

If the same disk holds several Linux installs on btrfs with @ subvolumes, Debian’s os-prober won’t detect them: it looks for /etc/os-release at the partition’s top level instead of inside /@/etc/os-release (upstream Debian bugs #921004 and #940710, still open). On SysLinuxOS with syslinuxos-snapshots ≥ 0.3.0 this is already handled automatically by a dedicated script that still surfaces them in the GRUB menu.

Notes on encrypted partitions

If another SysLinuxOS install lives on an encrypted partition, mount (unlock) it first so it gets detected, then run:

sudo update-grub

A word of caution

This is a standard GRUB recovery procedure, adapted to SysLinuxOS’s btrfs subvolume layout. Commands like grub-install write to the boot sector: always double-check the target disk (lsblk) before running these commands, especially with more than one disk attached.

Restoring GRUB on SysLinuxOS (btrfs with subvolumes)