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

✨ Quick Answer

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.

Quick Diagnostics

Cause

Btrfs filesystem errors caused by unexpected power loss

Solution

Check kernel log dmesg and run btrfs check --repair /dev/sdX

Cause

Storage drive damaged or switched to read-only fail-safe mode

Solution

Remount drive read/write: mount -o remount,rw /data

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