Skip to contentSkip to conversation

btrfs-progs: check: properly fix missing INODE_REF cases

PATCH In review Qu Wenruo 2 participants 5 messages Dec 17, 2025 – Jan 24 Btrfs file system

lore
Share & tools
lore

Qu Wenruo

author
#0 lore raw

cover btrfs-progs: check: properly fix missing INODE_REF cases

This is inspired by a recent corruption report that an INODE_REF key hits a bitflip and becomes UNKNOWN.8 key.

That cause missing INODE_REF, and unfortunately neither original nor lowmem mode can properly handle it.

For the original mode it just completely lacks the handling for such case, thus fallback to delete the good DIR_INDEX, making things worse.

For the lowmem mode, although it is trying to keep the good DIR_INDEX/DIR_ITEM, it doesn't handle index number search, thus using the default (-1) as index, causing incorrect new link to be added.

Fix both modes, and add a new test case for it.

Qu Wenruo (3):
btrfs-progs: check/original: add dedicated missing INODE_REF repair
btrfs-progs: check/lowmem: fix INODE_REF repair
btrfs-progs: fsck-tests: add a test case for repairing missing
INODE_REF

 check/main.c                                  |  51 ++++++++++++++++++
 check/mode-lowmem.c                           |  11 ++++
 .../070-missing-inode-ref/.lowmem_repairable  |   0
 .../070-missing-inode-ref/default.img.xz      | Bin 0 -> 2092 bytes
 4 files changed, 62 insertions(+)
 create mode 100644 tests/fsck-tests/070-missing-inode-ref/.lowmem_repairable
 create mode 100644 tests/fsck-tests/070-missing-inode-ref/default.img.xz

--
2.52.0

author
#1 lore raw

PATCH 1/3 btrfs-progs: check/original: add dedicated missing INODE_REF repair

Currently if the original mode of btrfs-check hits a missing INODE_REF, but with valid DIR_INDEX/DIR_ITEM, then it will repair it by deleting the valid DIR_INDEX, which will just make things worse.

Add a dedicated repair for missing INODE_REF which will just add back the missing INODE_REF, properly fixing the problem other than making it worse.

---
 check/main.c | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
check/main.c +51 -0
index 96c7ef7d8261..880827e11ee7 100644
@@ -2351,6 +2351,42 @@ static int create_inode_item(struct btrfs_root *root,
 	return 0;
 }
 
+static int create_inode_ref(struct btrfs_root *root,
+			    struct inode_record *i_rec,
+			    struct inode_backref *backref)
+{
+	struct btrfs_trans_handle *trans;
+	int ret;
+
+	trans = btrfs_start_transaction(root, 1);
+	if (IS_ERR(trans)) {
+		ret = PTR_ERR(trans);
+		errno = -ret;
+		error_msg(ERROR_MSG_START_TRANS, "%m");
+		return ret;
+	}
+
+	ret = btrfs_insert_inode_ref(trans, root, backref->name, backref->namelen,
+				     i_rec->ino, backref->dir, backref->index);
+	if (ret < 0) {
+		btrfs_commit_transaction(trans, root);
+		return ret;
+	}
+	ret = btrfs_commit_transaction(trans, root);
+	if (ret < 0) {
+		ret = PTR_ERR(trans);
+		errno = -ret;
+		error_msg(ERROR_MSG_COMMIT_TRANS, "%m");
+		return ret;
+	}
+	backref->found_inode_ref = 1;
+	backref->errors &= ~REF_ERR_NO_INODE_REF;
+	printf("Added INODE_REF for root %lld ino %llu parent %llu index %llu name %.*s\n",
+		btrfs_root_id(root), i_rec->ino, backref->dir, backref->index,
+		backref->namelen, backref->name);
+	return 0;
+}
+
 static int repair_inode_backrefs(struct btrfs_root *root,
 				 struct inode_record *rec,
 				 struct cache_tree *inode_cache,
@@ -2375,6 +2411,21 @@ static int repair_inode_backrefs(struct btrfs_root *root,
 		if (rec->ino == root_dirid && backref->index == 0)
 			continue;
 
+		/*
+		 * Have DIR_INDEX, DIR_ITEM and INODE_ITEM, and even nlinks
+		 * matches with only missing INODE_REF.
+		 */
+		if (!backref->found_inode_ref && backref->found_dir_item &&
+		    backref->found_dir_index && rec->found_inode_item &&
+		    rec->found_link == rec->nlink) {
+			ret = create_inode_ref(root, rec, backref);
+			if (ret)
+				break;
+			repaired++;
+			list_del(&backref->list);
+			free(backref);
+			continue;
+		}
 		if (delete &&
 		    ((backref->found_dir_index && !backref->found_inode_ref) ||
 		     (backref->found_dir_index && backref->found_inode_ref &&
Signature · 1 line
2.52.0
author
#2 lore raw

PATCH 2/3 btrfs-progs: check/lowmem: fix INODE_REF repair

In reply to Qu Wenruo

[BUG]
Although lowmem has the logical to repair one missing INODE_REF/DIR_INDEX/DIR_ITEM, there is a catch in missing INODE_REF.

If we're checking an DIR_ITEM (which we normally hits first), and failed to find the INODE_REF, we are in a situation where there is no @index to delete the original DIR_INDEX/DIR_ITEM pair.

This can cause further damage to the fs, without really improving anything.

[CAUSE]
There is a minimal example where there is missing INODE_ITEM:

item 0 key (256 INODE_ITEM 0) itemoff 16123 itemsize 160
generation 3 transid 9 size 12 nbytes 16384 block group 0 mode 40755 links 1 uid 0 gid 0 rdev 0 sequence 1 flags 0x0(none)
item 1 key (256 INODE_REF 256) itemoff 16111 itemsize 12
index 0 namelen 2 name: ..
item 2 key (256 DIR_ITEM 496027801) itemoff 16075 itemsize 36
location key (257 INODE_ITEM 0) type FILE transid 9 data_len 0 name_len 6
name: foobar
item 3 key (256 DIR_INDEX 2) itemoff 16039 itemsize 36
location key (257 INODE_ITEM 0) type FILE transid 9 data_len 0 name_len 6
name: foobar
item 4 key (257 INODE_ITEM 0) itemoff 15879 itemsize 160
generation 9 transid 9 size 0 nbytes 0 block group 0 mode 100644 links 1 uid 0 gid 0 rdev 0 sequence 1 flags 0x0(none)

For above case, if we're check the DIR_ITEM, we can find the INODE_ITEM but not the INODE_REF.

So we need to repair it, but at this stage we haven't checked DIR_INDEX, this means we have no idea which index we should delete, leaving the default @index as (-1).

If we call btrfs_unlink() with that (-1) as index, it will not delete the (256 DIR_INDEX 2) one, then re-add a link using -1 as index, causing more damage.

[FIX]
Before calling btrfs_unlink(), do an extra check on if we're called from DIR_ITEM checks (aka, @index is -1) and we only detected a missing INODE_REF yet.

If so, do find_dir_index() call to determine the DIR_INDEX, if that failed it means we have missing both DIR_INDEX and INODE_REF, thus should remove the lone DIR_ITEM instead.

With this enhancement, lowmem mode can properly fix the missing INODE_REF by adding it back.

---
 check/mode-lowmem.c | 11 +++++++++++
 1 file changed, 11 insertions(+)
check/mode-lowmem.c +11 -0
index 8a4c5bc1e10d..dcec6cc06510 100644
@@ -1015,6 +1015,17 @@ static int repair_ternary_lowmem(struct btrfs_root *root, u64 dir_ino, u64 ino,
 	int stage = 0;
 	int ret = 0;
 
+	/*
+	 * We miss an INODE_REF, and we're checking DIR_ITEM and hasn't yet
+	 * find the DIR_INDEX, thus there is no reliable index.
+	 * Try to locate one, this can be slow as we need to locate the DIR_INDEX
+	 * item from the directory.
+	 */
+	if (index == (u64)-1 && (err & INODE_REF_MISSING)) {
+		ret = find_dir_index(root, dir_ino, ino, &index, name, name_len, filetype);
+		if (ret < 0)
+			err |= DIR_INDEX_MISSING;
+	}
 	/*
 	 * stage shall be one of following valild values:
 	 *	0: Fine, nothing to do.
Signature · 1 line
2.52.0
author
#3 lore raw

PATCH 3/3 btrfs-progs: fsck-tests: add a test case for repairing missing INODE_REF

In reply to Qu Wenruo

The image is created by removing the INODE_REF for inode 257.

Now both original and lowmem mode should be able to repair it.

---
 .../070-missing-inode-ref/.lowmem_repairable     |   0
 .../070-missing-inode-ref/default.img.xz         | Bin 0 -> 2092 bytes
 2 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 tests/fsck-tests/070-missing-inode-ref/.lowmem_repairable
 create mode 100644 tests/fsck-tests/070-missing-inode-ref/default.img.xz
tests/fsck-tests/070-missing-inode-ref/.lowmem_repairable new file +0 -0
new file mode 100644
index 000000000000..e69de29bb2d1
tests/fsck-tests/070-missing-inode-ref/default.img.xz new file binary +0 -0
new file mode 100644
index 0000000000000000000000000000000000000000..15d95eed391c14630d93be2bf3e665186f816259
GIT binary patch
Signature · 1 line
2.52.0
#4 lore raw
In reply to Qu Wenruo
Quoted 14 lines · Qu Wenruo

This is inspired by a recent corruption report that an INODE_REF key hits a bitflip and becomes UNKNOWN.8 key.

That cause missing INODE_REF, and unfortunately neither original nor lowmem mode can properly handle it.

For the original mode it just completely lacks the handling for such case, thus fallback to delete the good DIR_INDEX, making things worse.

For the lowmem mode, although it is trying to keep the good DIR_INDEX/DIR_ITEM, it doesn't handle index number search, thus using the default (-1) as index, causing incorrect new link to be added.

Quoted 7 lines

Fix both modes, and add a new test case for it.

Qu Wenruo (3):
btrfs-progs: check/original: add dedicated missing INODE_REF repair
btrfs-progs: check/lowmem: fix INODE_REF repair
btrfs-progs: fsck-tests: add a test case for repairing missing
INODE_REF

Added to devel, thanks.