How to Repair a BTRFS Filesystem Locked in Read-Only Mode on Your Server

When a secondary hard drive configured with the modern BTRFS file system (very common in storage arrays and home servers like Umbrel or ZimaOS) detects a write error, a power outage, or corrupt sectors, the Linux kernel automatically changes its state to Read-Only to prevent existing information from being destroyed. This immediately freezes all your automation and download applications.

Step-by-Step Solution

1. 1

   Step 1: Desmontar la unidad afectada

   Do not attempt to force writing data onto a locked disk. First, stop the Docker services that are using it and unmount the path:

   BASH

   Copy

   sudo systemctl stop docker
   sudo umount /dev/sdb1
   

   (Reemplaza /dev/sdb1 por la nomenclatura exacta de tu disco detectado).

2. 2

   Step 2: Ejecutar una verificación de errores limpia (Check Scratch)

   We will use BTRFS internal tools to scan the storage metadata tree without modifying blocks:

   BASH

   Copy

   sudo btrfs check --readonly /dev/sdb1
   

   Read the last lines in the terminal. If the system reports minor errors in the free space map (free space cache), we can order a safe repair of the file descriptors by running:

   BASH

   Copy

   sudo btrfs check --repair /dev/sdb1
   

   (Nota: Ejecuta la reparación únicamente si el check previo te lo sugiere explícitamente).

3. 3

   Step 3: Remontar el disco en modo de rescate limpio

   If the volume continues to cause issues, force it to boot by cleaning the records of old corrupt transitions:

   BASH

   Copy

   sudo mount -o remount,clear_cache,rw /dev/sdb1 /mnt/storage