Skip to contentSkip to conversation

btrfs-progs: check: add detection for missing root orphan items

PATCH Superseded Qu Wenruo 2 participants 7 messages Jul 25, 2025 – Jul 26, 2025 Btrfs file system

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Qu Wenruo

author
#0 lore raw

cover btrfs-progs: check: add detection for missing root orphan items

There is an internal bug report that some half-dropped subvolume makes balance to fail.

It turns out that, the involved subvolume doesn't have an orphan item, this means the half-dropped subvolume is never going to be cleaned up.

Then at balance time, a reloc tree is created for that half-dropped subvolume, and since balance doesn't expect to get a half-dropped subvolume, it doesn't check the drop_process_key and increased ref on already dropped nodes.

The problem for progs is that, neither original mode nor lowmem detects this kind of problem.

Original mode has a bad logic which prevents us from calling the proper orphan item check.
Lowmem mode doesn't even take orphan item into consideration.

This series will add the detection part for btrfs-check, for both original and lowmem mode, with a hand crafted image for test.

Qu Wenruo (3):
btrfs-progs: check/original: detect missing orphan items correctly
btrfs-progs: check/lowmem: detect missing orphan items correctly
btrfs-progs: fsck-tests: a new test case for missing root orphan item

 check/main.c                                    |   3 +--
 check/mode-lowmem.c                             |  11 +++++++++++
 .../066-missing-root-orphan-item/default.img.xz | Bin 0 -> 13468 bytes
 .../066-missing-root-orphan-item/test.sh        |  14 ++++++++++++++
 4 files changed, 26 insertions(+), 2 deletions(-)
 create mode 100644 tests/fsck-tests/066-missing-root-orphan-item/default.img.xz
 create mode 100755 tests/fsck-tests/066-missing-root-orphan-item/test.sh

--
2.50.0

author
#4 lore raw

PATCH 2/3 btrfs-progs: check/lowmem: detect missing orphan items correctly

[BUG]
If we have a filesystem with a subvolume that has 0 refs but without an orphan item, btrfs check won't report any error on it.

  $ btrfs ins dump-tree -t root /dev/test/scratch1
  btrfs-progs v6.15
  root tree
  node 5242880 level 1 items 2 free space 119 generation 11 owner ROOT_TREE
  node 5242880 flags 0x1(WRITTEN) backref revision 1
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  chunk uuid 6c373b6d-c866-4c8c-81fa-608bf5ef25e3
  	key (EXTENT_TREE ROOT_ITEM 0) block 5267456 gen 11
  	key (ROOT_TREE_DIR DIR_ITEM 2378154706) block 5246976 gen 11
  leaf 5267456 items 6 free space 2339 generation 11 owner ROOT_TREE
  leaf 5267456 flags 0x1(WRITTEN) backref revision 1
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  	[...]
  leaf 5246976 items 6 free space 1613 generation 11 owner ROOT_TREE
  leaf 5246976 flags 0x1(WRITTEN) backref revision 1
  checksum stored 47620783
  checksum calced 47620783
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  chunk uuid 6c373b6d-c866-4c8c-81fa-608bf5ef25e3
  	[...]
  	item 4 key (256 ROOT_ITEM 0) itemoff 2202 itemsize 439
  		generation 9 root_dirid 256 bytenr 5898240 byte_limit 0 bytes_used 581632
  		last_snapshot 0 flags 0x1000000000000(none) refs 0 <<<
  		drop_progress key (0 UNKNOWN.0 0) drop_level 0
  		level 2 generation_v2 9
  	item 5 key (DATA_RELOC_TREE ROOT_ITEM 0) itemoff 1763 itemsize 439
  		generation 5 root_dirid 256 bytenr 5287936 byte_limit 0 bytes_used 4096
  		last_snapshot 0 flags 0x0(none) refs 1
  		drop_progress key (0 UNKNOWN.0 0) drop_level 0
  		level 0 generation_v2 5
  	^^^ No orphan item for subvolume 256.

Then "btrfs check --mode=lowmem" will not report anything wrong with it:

Opening filesystem to check...
Checking filesystem on /dev/test/scratch1
UUID: ff32309e-4e90-4402-b1ef-0a1f9f28bfff
[1/8] checking log skipped (none written)
[2/8] checking root items
[3/8] checking extents
[4/8] checking free space tree
[5/8] checking fs roots
[6/8] checking only csums items (without verifying data) [7/8] checking root refs done with fs roots in lowmem mode, skipping [8/8] checking quota groups skipped (not enabled on this FS) found 638976 bytes used, no error found <<
total csum bytes: 0
total tree bytes: 638976
total fs tree bytes: 589824
total extent tree bytes: 16384
btree space waste bytes: 289501
file data blocks allocated: 0
referenced 0

[CAUSE]
In lowmem's check_btrfs_root() we have no special handling for refs 0, as long as there is no ROOT_BACKREF for the orphan root, everything will be reported as OK.

But we should expect an orphan item for an orphan subvolume, this means lowmem doesn't do any checks against the orphan item for a subvolume.

[FIX]
For subvolume trees, if its refs is 0, also check if we have an orphan item for it.
If not, report this as an error.

---
 check/mode-lowmem.c | 11 +++++++++++
 1 file changed, 11 insertions(+)
check/mode-lowmem.c +11 -0
index 5291070df025..e05bb0da1709 100644
@@ -5502,6 +5502,17 @@ static int check_btrfs_root(struct btrfs_root *root, int check_all)
 			}
 		}
 	}
+	/*
+	 * If this tree is a subvolume (not a reloc tree) and has no refs, there
+	 * should be an orphan item for it, or this subvolume will never be deleted.
+	 */
+	if (btrfs_root_refs(root_item) == 0 && is_fstree(btrfs_root_id(root))) {
+		if (!has_orphan_item(root->fs_info->tree_root,
+				     btrfs_root_id(root))) {
+			error("missing orphan item for root %lld", btrfs_root_id(root));
+			err |= REFERENCER_MISSING;
+		}
+	}
 	if (btrfs_root_refs(root_item) > 0 ||
 	    btrfs_disk_key_objectid(&root_item->drop_progress) == 0) {
 		path.nodes[level] = root->node;
Signature · 1 line
2.50.0
author
#1 lore raw

PATCH 1/3 btrfs-progs: check/original: detect missing orphan items correctly

In reply to Qu Wenruo

[BUG]
If we have a filesystem with a subvolume that has 0 refs but without an orphan item, btrfs check won't report any error on it.

  $ btrfs ins dump-tree -t root /dev/test/scratch1
  btrfs-progs v6.15
  root tree
  node 5242880 level 1 items 2 free space 119 generation 11 owner ROOT_TREE
  node 5242880 flags 0x1(WRITTEN) backref revision 1
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  chunk uuid 6c373b6d-c866-4c8c-81fa-608bf5ef25e3
  	key (EXTENT_TREE ROOT_ITEM 0) block 5267456 gen 11
  	key (ROOT_TREE_DIR DIR_ITEM 2378154706) block 5246976 gen 11
  leaf 5267456 items 6 free space 2339 generation 11 owner ROOT_TREE
  leaf 5267456 flags 0x1(WRITTEN) backref revision 1
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  	[...]
  leaf 5246976 items 6 free space 1613 generation 11 owner ROOT_TREE
  leaf 5246976 flags 0x1(WRITTEN) backref revision 1
  checksum stored 47620783
  checksum calced 47620783
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  chunk uuid 6c373b6d-c866-4c8c-81fa-608bf5ef25e3
  	[...]
  	item 4 key (256 ROOT_ITEM 0) itemoff 2202 itemsize 439
  		generation 9 root_dirid 256 bytenr 5898240 byte_limit 0 bytes_used 581632
  		last_snapshot 0 flags 0x1000000000000(none) refs 0 <<<
  		drop_progress key (0 UNKNOWN.0 0) drop_level 0
  		level 2 generation_v2 9
  	item 5 key (DATA_RELOC_TREE ROOT_ITEM 0) itemoff 1763 itemsize 439
  		generation 5 root_dirid 256 bytenr 5287936 byte_limit 0 bytes_used 4096
  		last_snapshot 0 flags 0x0(none) refs 1
  		drop_progress key (0 UNKNOWN.0 0) drop_level 0
  		level 0 generation_v2 5
  	^^^ No orphan item for subvolume 256.

Then "btrfs check" will not report anything wrong with it:

Opening filesystem to check...
Checking filesystem on /dev/test/scratch1
UUID: ff32309e-4e90-4402-b1ef-0a1f9f28bfff
[1/8] checking log skipped (none written)
[2/8] checking root items
[3/8] checking extents
[4/8] checking free space tree
[5/8] checking fs roots
[6/8] checking only csums items (without verifying data) [7/8] checking root refs
[8/8] checking quota groups skipped (not enabled on this FS) found 638976 bytes used, no error found <<<
total csum bytes: 0
total tree bytes: 638976
total fs tree bytes: 589824
total extent tree bytes: 16384
btree space waste bytes: 289501
file data blocks allocated: 0
referenced 0

[CAUSE]
Although we have check_orphan_item() call inside check_root_refs(), it relies the root record to have its 'found_root_item' member set. Otherwise it will not report this as an error.

But that 'found_root_item' is always set to 0, if the subvolume has zero ref, this means any subvolume with 0 refs will not have its orphan item checked.

[FIX]
Set root_record::found_root_item to 1 inside check_fs_root().

As check_fs_root() is called after we found a root item, we should set root_record::found_root_item to indicate this fact, and allows proper orphan item check to be done.

---
 check/main.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
check/main.c +1 -2
index b78eb59d0c50..1536c1bbbccd 100644
@@ -3728,8 +3728,7 @@ static int check_fs_root(struct btrfs_root *root,
 	if (root->root_key.objectid != BTRFS_TREE_RELOC_OBJECTID) {
 		rec = get_root_rec(root_cache, root->root_key.objectid);
 		BUG_ON(IS_ERR(rec));
-		if (btrfs_root_refs(root_item) > 0)
-			rec->found_root_item = 1;
+		rec->found_root_item = 1;
 	}
 
 	memset(&root_node, 0, sizeof(root_node));
Signature · 1 line
2.50.0
author
#5 lore raw

PATCH 3/3 btrfs-progs: fsck-tests: a new test case for missing root orphan item

In reply to Qu Wenruo

The new image is created by:

- Make btrfs_delete_subvolume() to commit transaction
So that we're sure the orphan item is committed to disk after removing the subvolume.

- Remove the orphan item from tree root

Then use this image to make sure btrfs check can detect such problem. Repair is not yet supported.

---
 .../066-missing-root-orphan-item/default.img.xz | Bin 0 -> 13468 bytes
 .../066-missing-root-orphan-item/test.sh        |  14 ++++++++++++++
 2 files changed, 14 insertions(+)
 create mode 100644 tests/fsck-tests/066-missing-root-orphan-item/default.img.xz
 create mode 100755 tests/fsck-tests/066-missing-root-orphan-item/test.sh
tests/fsck-tests/066-missing-root-orphan-item/default.img.xz new file binary +0 -0
new file mode 100644
index 0000000000000000000000000000000000000000..c34f989daf0aef34e2692f2d11d4d4b1417ccdb5
GIT binary patch
tests/fsck-tests/066-missing-root-orphan-item/test.sh new file +14 -0
new file mode 100755
index 000000000000..9db625714c1f
@@ -0,0 +1,14 @@
+#!/bin/bash
+#
+# Verify that check can report missing orphan root itemm as an error
+
+source "$TEST_TOP/common" || exit
+
+check_prereq btrfs
+
+check_image() {
+	run_mustfail "missing root orphan item not reported as an error" \
+		"$TOP/btrfs" check "$1"
+}
+
+check_all_images
Signature · 1 line
2.50.0
#2 lore raw

Re: [PATCH 1/3] btrfs-progs: check/original: detect missing orphan items correctly

In reply to Qu Wenruo
Quoted 84 lines · Qu Wenruo

[BUG]
If we have a filesystem with a subvolume that has 0 refs but without an orphan item, btrfs check won't report any error on it.

  $ btrfs ins dump-tree -t root /dev/test/scratch1
  btrfs-progs v6.15
  root tree
  node 5242880 level 1 items 2 free space 119 generation 11 owner ROOT_TREE
  node 5242880 flags 0x1(WRITTEN) backref revision 1
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  chunk uuid 6c373b6d-c866-4c8c-81fa-608bf5ef25e3
  	key (EXTENT_TREE ROOT_ITEM 0) block 5267456 gen 11
  	key (ROOT_TREE_DIR DIR_ITEM 2378154706) block 5246976 gen 11
  leaf 5267456 items 6 free space 2339 generation 11 owner ROOT_TREE
  leaf 5267456 flags 0x1(WRITTEN) backref revision 1
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  	[...]
  leaf 5246976 items 6 free space 1613 generation 11 owner ROOT_TREE
  leaf 5246976 flags 0x1(WRITTEN) backref revision 1
  checksum stored 47620783
  checksum calced 47620783
  fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
  chunk uuid 6c373b6d-c866-4c8c-81fa-608bf5ef25e3
  	[...]
  	item 4 key (256 ROOT_ITEM 0) itemoff 2202 itemsize 439
  		generation 9 root_dirid 256 bytenr 5898240 byte_limit 0 bytes_used 581632
  		last_snapshot 0 flags 0x1000000000000(none) refs 0 <<<
  		drop_progress key (0 UNKNOWN.0 0) drop_level 0
  		level 2 generation_v2 9
  	item 5 key (DATA_RELOC_TREE ROOT_ITEM 0) itemoff 1763 itemsize 439
  		generation 5 root_dirid 256 bytenr 5287936 byte_limit 0 bytes_used 4096
  		last_snapshot 0 flags 0x0(none) refs 1
  		drop_progress key (0 UNKNOWN.0 0) drop_level 0
  		level 0 generation_v2 5
  	^^^ No orphan item for subvolume 256.

Then "btrfs check" will not report anything wrong with it:

Opening filesystem to check...
Checking filesystem on /dev/test/scratch1
UUID: ff32309e-4e90-4402-b1ef-0a1f9f28bfff
[1/8] checking log skipped (none written)
[2/8] checking root items
[3/8] checking extents
[4/8] checking free space tree
[5/8] checking fs roots
[6/8] checking only csums items (without verifying data) [7/8] checking root refs
[8/8] checking quota groups skipped (not enabled on this FS) found 638976 bytes used, no error found <<<
total csum bytes: 0
total tree bytes: 638976
total fs tree bytes: 589824
total extent tree bytes: 16384
btree space waste bytes: 289501
file data blocks allocated: 0
referenced 0

[CAUSE]
Although we have check_orphan_item() call inside check_root_refs(), it relies the root record to have its 'found_root_item' member set. Otherwise it will not report this as an error.

But that 'found_root_item' is always set to 0, if the subvolume has zero ref, this means any subvolume with 0 refs will not have its orphan item checked.

[FIX]
Set root_record::found_root_item to 1 inside check_fs_root().

As check_fs_root() is called after we found a root item, we should set root_record::found_root_item to indicate this fact, and allows proper orphan item check to be done.

---
 check/main.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
check/main.c +0 -0
index b78eb59d0c50..1536c1bbbccd 100644

check/main.c static int check_fs_root(struct btrfs_root *root, · line 3731

Quoted 6 lines
check/main.c +1 -2
@@ -3728,8 +3728,7 @@ static int check_fs_root(struct btrfs_root *root,
 	if (root->root_key.objectid != BTRFS_TREE_RELOC_OBJECTID) {
 		rec = get_root_rec(root_cache, root->root_key.objectid);
 		BUG_ON(IS_ERR(rec));
-		if (btrfs_root_refs(root_item) > 0)
-			rec->found_root_item = 1;
+		rec->found_root_item = 1;

This change feels like an improvement to me, but it does seem to implicitly reduce the fidelity of the root ref checking. Like if the root refs was 0 but a ref existed, then we would suddenly miss that, where before it was an error. I think it would be best to check that refs is correct (i.e., store the found refs and add up the refs we see and make sure they match), separate from the "found_root_item" logic.

Quoted 6 lines
check/main.c +0 -0
 	}
 
 	memset(&root_node, 0, sizeof(root_node));
Signature · 1 line
2.50.0
Reviewed-by on the v1 series
#6 lore raw
In reply to Qu Wenruo
Quoted 14 lines · Qu Wenruo

There is an internal bug report that some half-dropped subvolume makes balance to fail.

It turns out that, the involved subvolume doesn't have an orphan item, this means the half-dropped subvolume is never going to be cleaned up.

Then at balance time, a reloc tree is created for that half-dropped subvolume, and since balance doesn't expect to get a half-dropped subvolume, it doesn't check the drop_process_key and increased ref on already dropped nodes.

The problem for progs is that, neither original mode nor lowmem detects this kind of problem.

Quoted 6 lines

Original mode has a bad logic which prevents us from calling the proper orphan item check.
Lowmem mode doesn't even take orphan item into consideration.

This series will add the detection part for btrfs-check, for both original and lowmem mode, with a hand crafted image for test.

I left one idea on the check/original patch, but the series looks good overall to me, thanks for the fix.

Quoted 17 lines

Qu Wenruo (3):
btrfs-progs: check/original: detect missing orphan items correctly
btrfs-progs: check/lowmem: detect missing orphan items correctly
btrfs-progs: fsck-tests: a new test case for missing root orphan item

 check/main.c                                    |   3 +--
 check/mode-lowmem.c                             |  11 +++++++++++
 .../066-missing-root-orphan-item/default.img.xz | Bin 0 -> 13468 bytes
 .../066-missing-root-orphan-item/test.sh        |  14 ++++++++++++++
 4 files changed, 26 insertions(+), 2 deletions(-)
 create mode 100644 tests/fsck-tests/066-missing-root-orphan-item/default.img.xz
 create mode 100755 tests/fsck-tests/066-missing-root-orphan-item/test.sh

--
2.50.0

author
#3 lore raw

Re: [PATCH 1/3] btrfs-progs: check/original: detect missing orphan items correctly

In reply to Boris Burkov
Quoted 90 lines · Boris Burkov
Quoted 89 lines · Qu Wenruo

[BUG]
If we have a filesystem with a subvolume that has 0 refs but without an orphan item, btrfs check won't report any error on it.

   $ btrfs ins dump-tree -t root /dev/test/scratch1
   btrfs-progs v6.15
   root tree
   node 5242880 level 1 items 2 free space 119 generation 11 owner ROOT_TREE
   node 5242880 flags 0x1(WRITTEN) backref revision 1
   fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
   chunk uuid 6c373b6d-c866-4c8c-81fa-608bf5ef25e3
   	key (EXTENT_TREE ROOT_ITEM 0) block 5267456 gen 11
   	key (ROOT_TREE_DIR DIR_ITEM 2378154706) block 5246976 gen 11
   leaf 5267456 items 6 free space 2339 generation 11 owner ROOT_TREE
   leaf 5267456 flags 0x1(WRITTEN) backref revision 1
   fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
   	[...]
   leaf 5246976 items 6 free space 1613 generation 11 owner ROOT_TREE
   leaf 5246976 flags 0x1(WRITTEN) backref revision 1
   checksum stored 47620783
   checksum calced 47620783
   fs uuid ff32309e-4e90-4402-b1ef-0a1f9f28bfff
   chunk uuid 6c373b6d-c866-4c8c-81fa-608bf5ef25e3
   	[...]
   	item 4 key (256 ROOT_ITEM 0) itemoff 2202 itemsize 439
   		generation 9 root_dirid 256 bytenr 5898240 byte_limit 0 bytes_used 581632
   		last_snapshot 0 flags 0x1000000000000(none) refs 0 <<<
   		drop_progress key (0 UNKNOWN.0 0) drop_level 0
   		level 2 generation_v2 9
   	item 5 key (DATA_RELOC_TREE ROOT_ITEM 0) itemoff 1763 itemsize 439
   		generation 5 root_dirid 256 bytenr 5287936 byte_limit 0 bytes_used 4096
   		last_snapshot 0 flags 0x0(none) refs 1
   		drop_progress key (0 UNKNOWN.0 0) drop_level 0
   		level 0 generation_v2 5
   	^^^ No orphan item for subvolume 256.

Then "btrfs check" will not report anything wrong with it:

Opening filesystem to check...
Checking filesystem on /dev/test/scratch1
UUID: ff32309e-4e90-4402-b1ef-0a1f9f28bfff
[1/8] checking log skipped (none written)
[2/8] checking root items
[3/8] checking extents
[4/8] checking free space tree
[5/8] checking fs roots
[6/8] checking only csums items (without verifying data) [7/8] checking root refs
[8/8] checking quota groups skipped (not enabled on this FS) found 638976 bytes used, no error found <<<
total csum bytes: 0
total tree bytes: 638976
total fs tree bytes: 589824
total extent tree bytes: 16384
btree space waste bytes: 289501
file data blocks allocated: 0
referenced 0

[CAUSE]
Although we have check_orphan_item() call inside check_root_refs(), it relies the root record to have its 'found_root_item' member set. Otherwise it will not report this as an error.

But that 'found_root_item' is always set to 0, if the subvolume has zero ref, this means any subvolume with 0 refs will not have its orphan item checked.

[FIX]
Set root_record::found_root_item to 1 inside check_fs_root().

As check_fs_root() is called after we found a root item, we should set root_record::found_root_item to indicate this fact, and allows proper orphan item check to be done.

---
  check/main.c | 3 +--
  1 file changed, 1 insertion(+), 2 deletions(-)
check/main.c +0 -2
index b78eb59d0c50..1536c1bbbccd 100644
@@ -3728,8 +3728,7 @@ static int check_fs_root(struct btrfs_root *root,
  	if (root->root_key.objectid != BTRFS_TREE_RELOC_OBJECTID) {
  		rec = get_root_rec(root_cache, root->root_key.objectid);
  		BUG_ON(IS_ERR(rec));
-		if (btrfs_root_refs(root_item) > 0)
-			rec->found_root_item = 1;
Quoted 8 lines

check/main.c static int check_fs_root(struct btrfs_root *root, · line 3731

Quoted 1 line
check/main.c +1 -0
+		rec->found_root_item = 1;

This change feels like an improvement to me, but it does seem to implicitly reduce the fidelity of the root ref checking. Like if the root refs was 0 but a ref existed, then we would suddenly miss that, where before it was an error. I think it would be best to check that refs is correct (i.e., store the found refs and add up the refs we see and make sure they match), separate from the "found_root_item" logic.

That sounds great.

We indeed need to record the actually found root refs (the current found_ref) and the expected root refs in root item.

This looks easy enough, and I'll add that first.

Thanks,
Qu

Quoted 7 lines
Quoted 7 lines
check/main.c +0 -0
  	}
 
  	memset(&root_node, 0, sizeof(root_node));
Signature · 1 line
2.50.0