Skip to contentSkip to conversation

btrfs-progs: check: add repair ability for missing root orphan item

PATCH In review Qu Wenruo 2 participants 6 messages Nov 14, 2025 – Nov 19, 2025 1 message not in the archive Btrfs file system

lore
Share & tools
lore

Qu Wenruo

author
#0 lore raw

cover btrfs-progs: check: add repair ability for missing root orphan item

There is another report of missing root orphan item, although the latest btrfs-progs can detect such corruption, we have no way to fix it.

This makes the affected end users helpless, as the corruption can happen for affected old kernels, and that damage is persistent.

Add the repair ability to save those affected end users.

Qu Wenruo (2):
btrfs-progs: check: add repair ability for missing orphan root item
btrfs-progs: fsck-tests: make test case 066 to be repairable

 check/main.c                                  |  5 +++
 check/mode-common.c                           | 33 +++++++++++++++++++
 check/mode-common.h                           |  1 +
 check/mode-lowmem.c                           | 13 ++++++--
 .../.lowmem_repairable                        |  0
 .../066-missing-root-orphan-item/test.sh      | 14 --------
 6 files changed, 49 insertions(+), 17 deletions(-)
 create mode 100644 tests/fsck-tests/066-missing-root-orphan-item/.lowmem_repairable
 delete mode 100755 tests/fsck-tests/066-missing-root-orphan-item/test.sh

--
2.51.2

author
#1 lore raw

PATCH 1/2 btrfs-progs: check: add repair ability for missing orphan root item

There is a known bug in older kernels that orphan items can be missing for dropped subvolumes.

This makes those subvolumes unable to be removed on the next mount, and recent kernel commit 4289b494ac55 ("btrfs: do not allow relocation of partially dropped subvolumes") introduced one extra safe net to catch such problem.

But unfortunately there is no way to repair it.

Add the repair ability to both the original and lowmem modes.

---
 check/main.c        |  5 +++++
 check/mode-common.c | 33 +++++++++++++++++++++++++++++++++
 check/mode-common.h |  1 +
 check/mode-lowmem.c | 13 ++++++++++---
 4 files changed, 49 insertions(+), 3 deletions(-)
check/main.c +5 -0
index 77458a769028..db055ae194f8 100644
@@ -3550,6 +3550,11 @@ static int check_root_refs(struct btrfs_root *root,
 				 */
 				if (!rec->found_root_item)
 					continue;
+				if (opt_check_repair) {
+					ret = repair_subvol_orphan_item(gfs_info, rec->objectid);
+					if (!ret)
+						continue;
+				}
 				errors++;
 				fprintf(stderr, "fs tree %llu missing orphan item\n", rec->objectid);
 			}
check/mode-common.c +33 -0
index 0467ba28395e..2d11a96dfb7e 100644
@@ -1672,3 +1672,36 @@ int check_and_repair_super_num_devs(struct btrfs_fs_info *fs_info)
 	printf("Successfully reset super num devices to %u\n", found_devs);
 	return 0;
 }
+
+int repair_subvol_orphan_item(struct btrfs_fs_info *fs_info, u64 rootid)
+{
+	struct btrfs_root *tree_root = fs_info->tree_root;
+	struct btrfs_trans_handle *trans;
+	struct btrfs_path path = { 0 };
+	int ret;
+
+	trans = btrfs_start_transaction(tree_root, 1);
+	if (IS_ERR(trans)) {
+		ret = PTR_ERR(trans);
+		errno = -ret;
+		error_msg(ERROR_MSG_START_TRANS, "%m");
+		return ret;
+	}
+	ret = btrfs_add_orphan_item(trans, tree_root, &path, rootid);
+	btrfs_release_path(&path);
+	if (ret < 0) {
+		errno = -ret;
+		error("failed to insert orphan item for subvolume %llu: %m", rootid);
+		btrfs_abort_transaction(trans, ret);
+		btrfs_commit_transaction(trans, tree_root);
+		return ret;
+	}
+	ret = btrfs_commit_transaction(trans, tree_root);
+	if (ret < 0) {
+		errno = -ret;
+		error_msg(ERROR_MSG_COMMIT_TRANS, "%m");
+		return ret;
+	}
+	printf("Added back missing orphan item for subvolume %llu\n", rootid);
+	return 0;
+}
check/mode-common.h +1 -0
index c37b4dc00e54..e97835a5b6a3 100644
@@ -197,5 +197,6 @@ int repair_dev_item_bytes_used(struct btrfs_fs_info *fs_info,
 int fill_csum_tree(struct btrfs_trans_handle *trans, bool search_fs_tree);
 
 int check_and_repair_super_num_devs(struct btrfs_fs_info *fs_info);
+int repair_subvol_orphan_item(struct btrfs_fs_info *fs_info, u64 rootid);
 
 #endif
check/mode-lowmem.c +10 -3
index 363dc4ae1904..ea4d4017827f 100644
@@ -5569,9 +5569,16 @@ 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))) {
+	if (btrfs_root_refs(root_item) == 0 && is_fstree(btrfs_root_id(root)) &&
+	    !has_orphan_item(root->fs_info->tree_root, btrfs_root_id(root))) {
+		bool repaired = false;
+
+		if (opt_check_repair) {
+			ret = repair_subvol_orphan_item(root->fs_info, btrfs_root_id(root));
+			if (!ret)
+				repaired = true;
+		}
+		if (!repaired) {
 			error("missing orphan item for root %lld", btrfs_root_id(root));
 			err |= REFERENCER_MISSING;
 		}
Signature · 1 line
2.51.2
author
#3 lore raw

PATCH 2/2 btrfs-progs: fsck-tests: make test case 066 to be repairable

In reply to Qu Wenruo

The test case fsck/066 is only to verify we can detect the missing root orphan item, no repair for it yet.

Now the repair ability is added, change the test case to verify the repair is also properly done.

---
 .../.lowmem_repairable                             |  0
 .../066-missing-root-orphan-item/test.sh           | 14 --------------
 2 files changed, 14 deletions(-)
 create mode 100644 tests/fsck-tests/066-missing-root-orphan-item/.lowmem_repairable
 delete mode 100755 tests/fsck-tests/066-missing-root-orphan-item/test.sh
tests/fsck-tests/066-missing-root-orphan-item/.lowmem_repairable new file +0 -0
new file mode 100644
index 000000000000..e69de29bb2d1
tests/fsck-tests/066-missing-root-orphan-item/test.sh deleted +0 -14
deleted file mode 100755
index 9db625714c1f..000000000000
@@ -1,14 +0,0 @@
-#!/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.51.2
author
#5 lore raw

Re: [PATCH 2/2] btrfs-progs: fsck-tests: make test case 066 to be repairable

In reply to a message not in the archive
Quoted 11 lines · Goffredo Baroncelli
Quoted 5 lines · Qu Wenruo

The test case fsck/066 is only to verify we can detect the missing root orphan item, no repair for it yet.

Now the repair ability is added, change the test case to verify the repair is also properly done.

It seems more that this patch only can removed a test...

May be something was wrong ?

Nope, it's completely correct.

Check run_one_test() from tests/fsck-tests.sh.

There are tons of examples inside tests/fsck-tests/ where there are only test images without test.sh.

Test.sh are all utilized to override the existing check_image() which is not the full default check-repair-check run.

Thanks,
Qu

Quoted 36 lines
Quoted 34 lines

---
  .../.lowmem_repairable                             |  0 .../066-missing-root-orphan-item/test.sh           | 14 --------------

  2 files changed, 14 deletions(-)

  create mode 100644 tests/fsck-tests/066-missing-root-orphan- item/.lowmem_repairable delete mode 100755 tests/fsck-tests/066-missing-root-orphan-item/ test.sh

tests/fsck-tests/066-missing-root-orphan- item/.lowmem_repairable new file +0 -0
new file mode 100644
index 000000000000..e69de29bb2d1
tests/fsck-tests/066-missing-root-orphan-item/test.sh deleted +0 -14
deleted file mode 100755
index 9db625714c1f..000000000000
@@ -1,14 +0,0 @@
-#!/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
Reviewed-by on v1 1/2
#2 lore raw

Re: [PATCH 1/2] btrfs-progs: check: add repair ability for missing orphan root item

In reply to Qu Wenruo
Quoted 8 lines · Qu Wenruo

There is a known bug in older kernels that orphan items can be missing for dropped subvolumes.

This makes those subvolumes unable to be removed on the next mount, and recent kernel commit 4289b494ac55 ("btrfs: do not allow relocation of partially dropped subvolumes") introduced one extra safe net to catch such problem.

Quoted 6 lines

But unfortunately there is no way to repair it.

Add the repair ability to both the original and lowmem modes.

Quoted 102 lines
---
 check/main.c        |  5 +++++
 check/mode-common.c | 33 +++++++++++++++++++++++++++++++++
 check/mode-common.h |  1 +
 check/mode-lowmem.c | 13 ++++++++++---
 4 files changed, 49 insertions(+), 3 deletions(-)
check/main.c +5 -0
index 77458a769028..db055ae194f8 100644
@@ -3550,6 +3550,11 @@ static int check_root_refs(struct btrfs_root *root,
 				 */
 				if (!rec->found_root_item)
 					continue;
+				if (opt_check_repair) {
+					ret = repair_subvol_orphan_item(gfs_info, rec->objectid);
+					if (!ret)
+						continue;
+				}
 				errors++;
 				fprintf(stderr, "fs tree %llu missing orphan item\n", rec->objectid);
 			}
check/mode-common.c +33 -0
index 0467ba28395e..2d11a96dfb7e 100644
@@ -1672,3 +1672,36 @@ int check_and_repair_super_num_devs(struct btrfs_fs_info *fs_info)
 	printf("Successfully reset super num devices to %u\n", found_devs);
 	return 0;
 }
+
+int repair_subvol_orphan_item(struct btrfs_fs_info *fs_info, u64 rootid)
+{
+	struct btrfs_root *tree_root = fs_info->tree_root;
+	struct btrfs_trans_handle *trans;
+	struct btrfs_path path = { 0 };
+	int ret;
+
+	trans = btrfs_start_transaction(tree_root, 1);
+	if (IS_ERR(trans)) {
+		ret = PTR_ERR(trans);
+		errno = -ret;
+		error_msg(ERROR_MSG_START_TRANS, "%m");
+		return ret;
+	}
+	ret = btrfs_add_orphan_item(trans, tree_root, &path, rootid);
+	btrfs_release_path(&path);
+	if (ret < 0) {
+		errno = -ret;
+		error("failed to insert orphan item for subvolume %llu: %m", rootid);
+		btrfs_abort_transaction(trans, ret);
+		btrfs_commit_transaction(trans, tree_root);
+		return ret;
+	}
+	ret = btrfs_commit_transaction(trans, tree_root);
+	if (ret < 0) {
+		errno = -ret;
+		error_msg(ERROR_MSG_COMMIT_TRANS, "%m");
+		return ret;
+	}
+	printf("Added back missing orphan item for subvolume %llu\n", rootid);
+	return 0;
+}
check/mode-common.h +1 -0
index c37b4dc00e54..e97835a5b6a3 100644
@@ -197,5 +197,6 @@ int repair_dev_item_bytes_used(struct btrfs_fs_info *fs_info,
 int fill_csum_tree(struct btrfs_trans_handle *trans, bool search_fs_tree);
 
 int check_and_repair_super_num_devs(struct btrfs_fs_info *fs_info);
+int repair_subvol_orphan_item(struct btrfs_fs_info *fs_info, u64 rootid);
 
 #endif
check/mode-lowmem.c +10 -3
index 363dc4ae1904..ea4d4017827f 100644
@@ -5569,9 +5569,16 @@ 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))) {
+	if (btrfs_root_refs(root_item) == 0 && is_fstree(btrfs_root_id(root)) &&
+	    !has_orphan_item(root->fs_info->tree_root, btrfs_root_id(root))) {
+		bool repaired = false;
+
+		if (opt_check_repair) {
+			ret = repair_subvol_orphan_item(root->fs_info, btrfs_root_id(root));
+			if (!ret)
+				repaired = true;
+		}
+		if (!repaired) {
 			error("missing orphan item for root %lld", btrfs_root_id(root));
 			err |= REFERENCER_MISSING;
 		}
Signature · 1 line
2.51.2
Reviewed-by on v1 2/2
#6 lore raw

Re: [PATCH 2/2] btrfs-progs: fsck-tests: make test case 066 to be repairable

In reply to Qu Wenruo
Quoted 7 lines · Qu Wenruo

The test case fsck/066 is only to verify we can detect the missing root orphan item, no repair for it yet.

Now the repair ability is added, change the test case to verify the repair is also properly done.

Quoted 33 lines
---
 .../.lowmem_repairable                             |  0
 .../066-missing-root-orphan-item/test.sh           | 14 --------------
 2 files changed, 14 deletions(-)
 create mode 100644 tests/fsck-tests/066-missing-root-orphan-item/.lowmem_repairable
 delete mode 100755 tests/fsck-tests/066-missing-root-orphan-item/test.sh
tests/fsck-tests/066-missing-root-orphan-item/.lowmem_repairable new file +0 -0
new file mode 100644
index 000000000000..e69de29bb2d1
tests/fsck-tests/066-missing-root-orphan-item/test.sh deleted +0 -14
deleted file mode 100755
index 9db625714c1f..000000000000
@@ -1,14 +0,0 @@
-#!/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.51.2