Add, Inspect and Safely Remove Btrfs Devices

You will finish with a practical workflow for inspecting a mounted Btrfs filesystem, adding a device, checking persistent device error counters, and understanding the conditions for removal. The examples match btrfs-progs 6.6.3, the installed version used for this guide. Allow 20 to 30 minutes for inspection; adding or removing storage can take longer and should be planned separately.

You need a mounted Btrfs filesystem, an unused block device for an add operation, and root privileges for most device-management commands. Substitute your own mount point for /mnt/btrfs and your own device for /dev/sdb. Never use a guessed device path: check it with lsblk first.

1. Confirm the command and the target filesystem

Start with read-only checks. These do not need elevated privileges unless your system restricts access to the device information:

$ btrfs --version
btrfs-progs v6.6.3
$ findmnt -t btrfs
TARGET   SOURCE    FSTYPE OPTIONS
/mnt/btrfs /dev/sda btrfs  rw,relatime
$ lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS

The findmnt result is host-specific. Confirm that the path you will pass to btrfs device is the mounted filesystem, not a directory inside it. Device management in this command group works on a mounted filesystem.

2. Inspect allocation before changing anything

Use usage to see device size, slack, allocated data and metadata profiles, and unallocated space:

$ sudo btrfs device usage /mnt/btrfs
/dev/sda, ID: 1
   Device size:           100.00GiB
   Device slack:              0.00B
   Data,single:            18.00GiB
   Metadata,single:         2.00GiB
   System,single:          32.00MiB
   Unallocated:            80.00GiB

The numbers are examples, not expected values. Device size is the size Btrfs sees, which may differ from the physical device size. Device slack is space made available by an earlier shrink. Unallocated is space available for new block groups. A normal user can receive a warning that detailed per-device usage needs root, so use sudo when the allocation breakdown matters.

Profiles are independent for data, metadata and system block groups. A line such as Data,RAID1 describes Btrfs allocation policy, not necessarily a hardware RAID controller. Treat RAID names as Btrfs profiles and check the number and sizes of devices before predicting usable capacity.

3. Add an unused device

Adding a device changes the filesystem metadata immediately, so this is an elevated and persistent operation. It does not copy existing data onto the new device. Btrfs will use the additional space as new block groups become available.

First check the exact device:

$ lsblk -o NAME,MODEL,SERIAL,SIZE,FSTYPE,MOUNTPOINTS /dev/sdb
NAME MODEL  SERIAL SIZE FSTYPE MOUNTPOINTS
sdb  Example 1234  100G

If FSTYPE or MOUNTPOINTS shows anything unexpected, do not continue. The normal add command is:

$ sudo btrfs device add /dev/sdb /mnt/btrfs
$ sudo btrfs device usage /mnt/btrfs

On this version, adding may perform a whole-device discard before the device is added. Use --nodiscard if that default is unsuitable for the device, and use --force only when you have deliberately confirmed that overwriting an existing filesystem signature is safe. Force is destructive to the signature on the supplied device; it is not a general repair option.

4. Check persistent IO error counters

Run device statistics against the mounted filesystem or one of its devices:

$ sudo btrfs device stats /mnt/btrfs
[/dev/sda].write_io_errs   0
[/dev/sda].read_io_errs    0
[/dev/sda].flush_io_errs   0
[/dev/sda].corruption_errs 0
[/dev/sda].generation_errs 0

The counters record classes of IO and integrity errors and persist with the filesystem's device information. Non-zero values deserve investigation of the kernel log, cables, controller and device health before you treat the filesystem as healthy. A zero result is not a substitute for backups or a scrub.

For a monitoring check, --check returns zero when all counters are zero. On btrfs-progs 6.6.3, a non-zero counter adds 64 to the command's exit status, while 64 and 65 also identify statistics-reading failures described by the installed manual. Capture the status immediately:

$ sudo btrfs device stats --check /mnt/btrfs
$ printf 'stats exit status: %s\n' "$?"
stats exit status: 0

Do not use --reset as a first response to an alert. It prints the counters and then clears them, which removes useful evidence. Reset only after recording the output and completing the investigation:

$ sudo btrfs device stats --reset /mnt/btrfs

5. Remove a device only after checking profiles

Removal is a data-moving operation and can take a long time. It also cannot violate the active profile constraints. For example, removing one member from a two-device RAID1 filesystem fails because the remaining filesystem would no longer meet the profile's two-device requirement.

Do not convert profiles merely to remove a failing device. A balance may write new chunks onto the failing device. Use the separate btrfs replace workflow for a failing member. For a healthy device that you intentionally want to retire, plan the profile change, available workspace and redundancy impact first.

After those checks, the ordinary removal command is:

$ sudo btrfs device remove /dev/sdb /mnt/btrfs
$ sudo btrfs device usage /mnt/btrfs

Btrfs moves the device's data before completing the operation. Keep the filesystem mounted and avoid treating a returned prompt as proof that the device has disappeared: verify the usage output. If several devices are listed, removal happens one at a time. The installed command has a safety timeout for this case; --force skips that timeout but does not override profile constraints. Do not use it casually.

For a filesystem mounted in degraded mode, the special device name missing can remove a device recorded in the metadata but absent at mount time. Use it only when you understand the degraded mount and the missing-device count. In RAID6, for example, more than one missing device may require repeating missing.

6. Handle discovery and startup scans

Multi-device filesystems sometimes need their devices registered before an automated mount. Scan specific devices when you know which members are present:

$ sudo btrfs device scan /dev/sda /dev/sdb
$ sudo btrfs device ready /dev/sda

With no device arguments, scan uses blkid to find devices reporting Btrfs. --all-devices is the fallback when blkid is unavailable. Repeating a scan is safe for already registered devices. ready waits for the group to be registered, but it does not guarantee that the eventual mount will succeed.

--forget unregisters a device or stale devices. The relevant filesystem must be unmounted, so treat it as maintenance work and check mounts before running it:

$ findmnt -t btrfs
$ sudo btrfs device scan --forget /dev/sdb

If the device is still part of a mounted filesystem, the command should fail rather than unregister it. Do not turn that failure into a reason to stop the filesystem or remove a device without a recovery plan.