Skip to content

Instantly share code, notes, and snippets.

@ifazral
Last active July 5, 2026 13:34
Show Gist options
  • Select an option

  • Save ifazral/8bc3cb27b1abd4e6b9c205ef6940b9f1 to your computer and use it in GitHub Desktop.

Select an option

Save ifazral/8bc3cb27b1abd4e6b9c205ef6940b9f1 to your computer and use it in GitHub Desktop.
btrfs uki manual recovery guide

Complete Disaster Recovery Guide: Btrfs + UKI System Rollback & Driver Rescue

This comprehensive guide outlines the exact, step-by-step procedure to manually roll back an Arch Linux system utilizing systemd-boot, Unified Kernel Images (UKI), Btrfs subvolumes, and Snapper when the system is unbootable, followed by fixing the missing kernel modules and broken Snapper bindings entirely offline.


Phase 0: The Manual Btrfs Snapshot Rollback (Via Live USB)

When your system is completely broken or stuck on a black screen, you cannot use automated tools. You must boot into any Arch Linux Live USB and manually swap the subvolumes using the Btrfs command-line tools.

1. Boot the Live USB and Mount the Top-Level Volume

Once inside the Live USB terminal, create a mount point and mount the root of your Btrfs partition (subvolid=5) to access all subvolumes. (Replace /dev/nvme0n1p2 with your actual root partition).

mount /dev/nvme0n1p2 /mnt -o subvolid=5

2. Locate Your Target Clean Snapshot

List the contents of your subvolumes to see your current root (@) and locate where your Snapper snapshots are kept. (If your .snapshots directory is nested inside @, it will be accessible under /mnt/@/.snapshots/).

ls /mnt/@/.snapshots/

Identify the snapshot number you want to revert to (e.g., 116).

3. Move the Broken Root Subvolume Out of the Way

Rename your current broken root subvolume to something temporary like @_bozuk so you don't lose any files and can steal working drivers from it later.

mv /mnt/@ /mnt/@_bozuk

4. Create a Read-Write Clone of the Clean Snapshot

Snapper snapshots are read-only by default. To make it your new working root, you must create a writable snapshot clone named exactly @ from the target backup path:

btrfs subvolume snapshot /mnt/@_bozuk/.snapshots/116/snapshot /mnt/@

5. Unmount and Reboot Into the Host System

The subvolume swap is complete. Unmount the drive and reboot into your main machine.

umount /mnt
reboot

Phase 1: The Offline Driver Rescue Operation

After booting into your rolled-back system, you will notice a complete loss of Wi-Fi/Ethernet and sound, along with slow boot times. This is the "Time Paradox" effect: your system booted with the latest kernel, but your old 09:00 AM snapshot does not have the newer driver files (/usr/lib/modules/) yet.

Let's copy them from the broken system entirely offline:

1. Mount the Top-Level Volume Again (On Host Desktop)

Open a normal terminal on your host system:

sudo mount /dev/nvme0n1p2 /mnt -o subvolid=5

2. Copy the Latest Suffix Modules

Clone the newer driver folders from your saved @_bozuk partition directly into your current active root (@):

sudo cp -r /mnt/@_bozuk/usr/lib/modules/* /usr/lib/modules/

3. Unmount and Reboot

sudo umount /mnt
sudo reboot

Result: Boot times will instantly drop to seconds, and network/sound drivers will be fully restored.


Phase 2: Resolving Snapper IO & Subvolume Errors

Because the original .snapshots directory was physically inside the old root subvolume, it is now trapped inside @_bozuk. Running pacman will throw an IO Error (.snapshots is not a btrfs subvolume). Let's return it to its proper place.

1. Mount the Top-Level Volume

sudo mount /dev/nvme0n1p2 /mnt -o subvolid=5

2. Delete the Fake Empty Placeholder

Your new root generated an empty, standalone folder named .snapshots. Wipe it out so we can replace it:

sudo rm -rf /mnt/@/.snapshots

3. Relocate the Original Snapper Subvolume

Move your actual snapshot history back into the active root layout:

sudo mv /mnt/@_bozuk/.snapshots /mnt/@/.snapshots

4. Clean Up and Verify Snapper

sudo umount /mnt
sudo snapper list

Result: Your entire snapshot timeline will load flawlessly without errors.


Phase 3: Syncing Pacman, DKMS, and GPU Drivers

Since we manually pasted raw files into system directories, the package manager and the dynamic kernel module tree must be synchronized to prevent future upgrade conflicts.

1. Force Reinstall Kernel & Headers

Force pacman to overwrite the manually copied module files so they are properly tracked by the system database again:

sudo pacman -S linux-zen linux-zen-headers --overwrite "/usr/lib/modules/*"

(Adjust linux-zen to your specific kernel flavor).

2. Force Rebuild Hardware Surcharges (Nvidia DKMS)

If your GPU drivers fail to register during the upgrade step because files already exist, force DKMS to overwrite and stamp them officially:

sudo dkms install nvidia/[driver-version] -k [kernel-version] --force

Example: sudo dkms install nvidia/610.43.02 -k 7.0.13-zen1-1-zen --force


Phase 4: Regenerating the Unified Kernel Image (UKI)

The absolute final step is to lock all these kernel fixes and drivers natively into your UEFI boot partition by rebuilding your unified binary (.efi) image.

sudo mkinitcpio -P

Once the terminal outputs: ==> Creating unified kernel image: '/boot/EFI/Linux/arch-linux-zen.efi' ==> Unified kernel image generation successful

Your modern Arch Linux system is officially 100% stable, fully operational, and fully updated.


💡 Pro-Tip for Future Rollbacks

To completely avoid using Live USBs and TTY commands for rollbacks, install btrfs-assistant from the AUR.

As long as your system boots into a terminal or desktop interface, you can simply launch btrfs-assistant, navigate to the Snapper tab, select any historical restore point, and click Restore. It handles the subvolume cleanup and configuration linking automatically behind the scenes in milliseconds.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment