[PATCH v2 0/2] btrfs-progs: enhance detection on unknown keys in subvolumes

[PATCH v2 0/2] btrfs-progs: enhance detection on unknown keys in subvolumes

[Qu Wenruo]

[CHANGELOG]
v2:
- Add a new test case

This is inspired by a real world bitflip corruption, where an INODE_REF
is now 8 (an unknown key type), causing btrfs-check to freak out and the
existing INODE_REF/DIR_ITEM/DIR_INDEX repair is not cutting this
particular case for the original mode.

Lowmem mode is better, but for this particular image it's too large and
lowmem is too slow to be practical.

As the first step, detect and report such unknown keys in subvolume
trees as an error.

With a new test case for it.

In the long run we should allow btrfs-check --repair to delete such
unknown keys.

Qu Wenruo (2):
  btrfs-progs: enhance detection on unknown inode keys
  btrfs-progs: add a test case for unknown keys in subvolume trees

 check/main.c                                     |   7 +++++++
 check/mode-lowmem.c                              |   5 +++--
 check/mode-lowmem.h                              |   1 +
 tests/fsck-tests/069-unknown-fs-tree-key/test.sh |  14 ++++++++++++++
 .../unknown_key_empty.img.xz                     | Bin 0 -> 2084 bytes
 5 files changed, 25 insertions(+), 2 deletions(-)
 create mode 100755 tests/fsck-tests/069-unknown-fs-tree-key/test.sh
 create mode 100644 tests/fsck-tests/069-unknown-fs-tree-key/unknown_key_empty.img.xz

--
2.52.0

[PATCH v2 1/2] btrfs-progs: enhance detection on unknown inode keys

[Qu Wenruo]

There is a bug report that a bitflip corrupted one tree block, causing
a corruption that can not be repaired by btrfs-check.

The corruption looks like this:

	item 10 key (730455 INODE_ITEM 0) itemoff 15456 itemsize 160
		generation 7280 transid 9794 size 13829 nbytes 16384
		block group 0 mode 100600 links 1 uid 1000 gid 1000 rdev 0
		sequence 11 flags 0x0(none)
		atime 1765397443.29231914 (2025-12-11 06:40:43)
		ctime 1764798591.882909548 (2025-12-04 08:19:51)
		mtime 1764798591.882909548 (2025-12-04 08:19:51)
		otime 1764712848.413821734 (2025-12-03 08:30:48)
	item 11 key (730455 UNKNOWN.8 1924) itemoff 15406 itemsize 50

Note item 11, it has a unknown key, but the itemsize indicates it's an
INODE_REF with 40 name_len (which matches the DIR_ITEM).

bin(BTRFS_INODE_REF_KEY) = 0b1100
bin(8)                   = 0b1000

So it's indeed a bitflip.

At least we should report such unknown inode key types as errors.

The lowmem mode is already doing such report, although not treating them as
an error.
The original mode just ignores them completely.

So this patch enhance btrfs check to:

- Report such unknown item and treat them as error for the original mode

- Treat such unknown item as error for the lowmem mode

Reported-by: mikkel+btrfs@mikkel.cc
Link: https://lore.kernel.org/linux-btrfs/5d5e344e-96be-4436-9a58-d60ba14fdb4f@gmx.com/T/#me22cef92653e660e88a4c005b10f5201a8fd83ac
Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 check/main.c        | 7 +++++++
 check/mode-lowmem.c | 5 +++--
 check/mode-lowmem.h | 1 +
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/check/main.c b/check/main.c
index db055ae194f8..96c7ef7d8261 100644
--- a/check/main.c
+++ b/check/main.c
@@ -87,6 +87,7 @@ bool is_free_space_tree = false;
 bool init_extent_tree = false;
 bool check_data_csum = false;
 static bool found_free_ino_cache = false;
+static bool found_unknown_key = false;
 struct cache_tree *roots_info_cache = NULL;
 
 enum btrfs_check_mode {
@@ -1895,6 +1896,10 @@ static int process_one_leaf(struct btrfs_root *root, struct extent_buffer *eb,
 			ret = process_xattr_item(eb, i, &key, active_node);
 			break;
 		default:
+			error("Unknown key (%llu %u %llu) found in leaf %llu",
+			      key.objectid, key.type, key.offset,
+			      eb->start);
+			found_unknown_key = true;
 			break;
 		};
 	}
@@ -4027,6 +4032,8 @@ out:
 		free_extent_cache_tree(&wc.shared);
 	if (!cache_tree_empty(&wc.shared))
 		fprintf(stderr, "warning line %d\n", __LINE__);
+	if (!err && found_unknown_key)
+		err = 1;
 
 	return err;
 }
diff --git a/check/mode-lowmem.c b/check/mode-lowmem.c
index ea4d4017827f..8a4c5bc1e10d 100644
--- a/check/mode-lowmem.c
+++ b/check/mode-lowmem.c
@@ -2808,8 +2808,9 @@ static int check_inode_item(struct btrfs_root *root, struct btrfs_path *path)
 		case BTRFS_XATTR_ITEM_KEY:
 			break;
 		default:
-			error("ITEM[%llu %u %llu] UNKNOWN TYPE",
-			      key.objectid, key.type, key.offset);
+			error("ITEM[%llu %u %llu] UNKNOWN TYPE in leaf %llu",
+			      key.objectid, key.type, key.offset, node->start);
+			err |= UNKNOWN_KEY;
 		}
 	}
 
diff --git a/check/mode-lowmem.h b/check/mode-lowmem.h
index cd0355465be9..ec199b4c8008 100644
--- a/check/mode-lowmem.h
+++ b/check/mode-lowmem.h
@@ -48,6 +48,7 @@
 #define INVALID_GENERATION	(1U << 26)	/* Generation is too new */
 #define SUPER_BYTES_USED_ERROR	(1U << 27)	/* Super bytes_used is invalid */
 #define DUP_FILENAME_ERROR	(1U << 28)	/* DIR_ITEM contains duplicate names */
+#define UNKNOWN_KEY		(1U << 29)	/* Found unknown key type in fs trees */
 
 /*
  * Error bit for low memory mode check.
-- 
2.52.0

[PATCH v2 2/2] btrfs-progs: add a test case for unknown keys in subvolume trees

[Qu Wenruo]

The image has the following corrupted key in fs tree:

	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)
	item 5 key (257 UNKNOWN.8 256) itemoff 15879 itemsize 0 <<<
	item 6 key (257 INODE_REF 256) itemoff 15863 itemsize 16
		index 2 namelen 6 name: foobar

This is inspired by a real world memory bitflip, which lead to a bitflip
from 12 to 8, causing the above unknown key type in a subvolume.

Although we will need to properly enhance btrfs-check to handle such
case better, let's start from detecting and report such unknown keys as
an error.

The image is created by inserting an empty item with above unknown key
type.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 tests/fsck-tests/069-unknown-fs-tree-key/test.sh |  14 ++++++++++++++
 .../unknown_key_empty.img.xz                     | Bin 0 -> 2084 bytes
 2 files changed, 14 insertions(+)
 create mode 100755 tests/fsck-tests/069-unknown-fs-tree-key/test.sh
 create mode 100644 tests/fsck-tests/069-unknown-fs-tree-key/unknown_key_empty.img.xz

diff --git a/tests/fsck-tests/069-unknown-fs-tree-key/test.sh b/tests/fsck-tests/069-unknown-fs-tree-key/test.sh
new file mode 100755
index 000000000000..ea4f04e284be
--- /dev/null
+++ b/tests/fsck-tests/069-unknown-fs-tree-key/test.sh
@@ -0,0 +1,14 @@
+#!/bin/bash
+#
+# Verify that check can report unknown key types in subvolume trees
+
+source "$TEST_TOP/common" || exit
+
+check_prereq btrfs
+
+check_image() {
+	run_mustfail "unknown keys in subvolume trees not reported as error" \
+		"$TOP/btrfs" check "$1"
+}
+
+check_all_images
diff --git a/tests/fsck-tests/069-unknown-fs-tree-key/unknown_key_empty.img.xz b/tests/fsck-tests/069-unknown-fs-tree-key/unknown_key_empty.img.xz
new file mode 100644
index 0000000000000000000000000000000000000000..300a7cc92b7125d0309be6917195695610a0f549
GIT binary patch
literal 2084
zcmexsUKJ6=z`*kC+7>sK15fxH6cic77$D%d(EGFp{QueS#4@<f>{}kWZ}Y*EQkChu
z9osZa4txmpyS7W^PUOtzZ)&&if9>k%lb~ky%#P*O-IJ4Nd-&{~9V7GO{WPtBtA}h@
zl25L`*1gb!hwa0HSpDaAD#w$OmDVj;T-ctF8*^!~oWQ27kJo&t=HFVle{0W$=6zQZ
zxD(g4eERM(g?q)P3u?t7XS7l!rl`&lT9%}~(lONNHQT@Q_kL!+*~qw7P_Odv-}p04
z#|~Ydy*vAKLc=!2{S4L_diSsMM%+tdn9Pv9(bXmWjew2Qf=f|a+VlQDJhP8U^Y_+e
zal!$UFX|=qRVqC-3|whs6#8n~$Fi5ktn~~#3X_}KMSr>cn}3KmF|kiV(WB#Sb@;FT
zpB>I?&uyGv{do8G+&qyiH-_aue;>Qpb@2DkM5Q?^=6_F~d+wJ>hoq|P%V)>jjjz_U
zrf-YQQL%Y(<hoPDwZvy%J*-9dc=I--Z7pPH6iH5%lD<1x;Fp{gb6ea?lOs+K_gjn0
zX04aGk`(Qeo^7~jb&A%qhljKKL^i*BdZWnAjQ!{h@heX3e7>@;ygTz$BJ<UsJoR9T
zd!V;}YPXZdgVjb?wp@0)e8=x8zwVrak<6|t*RsMt=4h<ww(4O#v3&WtMwJgAj5Lfi
zqFbY8f4%o|rfBHo=BwMU*R%U9+r9SvC-2YQhisI!Wy_Z>Nc2dYUwCHX>G-f$q5A#x
z|Nr#`Z0c^yTAjF2J#zgs$q7$mlKuF?`juDDdUof(^uch`3r{@64qx@SyJ2Z>m~o+M
ztMOyE*uQsTSDp~MxBlNNt%ki9R;^vucW(Oa#wA;wzH*7zrG4$vtY{6eEDSI3>g8?8
ze#e}rxO=02MAPA8DXQ0BM@$vq5D(DVB2lmXW!Bf3jlbK{j)$B}462{?=>5gM8-H^%
zXU_Z@CvoPLyx=B{uro1hj=tnn*APfLwB+T%iz1V^XrC&+t~q7hkG@%F6K06mt)2g?
zBc$+(K~vsVZ|??+($INgGuKSu(KX>_meaH^owsZ1f&-aH!nGc5o8Pr^;jX_6(j&M1
zFscdL_9gXJ_2pFM-W?*^N;OX$U4l|=>!03m7yo(jTib0PQI?`2y~KszqJsP%Jid_V
zzw4TauioTc%f+uwu)N#wG&I?Y+f#Lm%+CH>8q6nd9eos`B4$)q!W|>+;dL`N{O~qw
z{zNPBa394YQ<;>oZO`=_G`>~m%nCKU*<*R|M18&lJM*!Q5c#vqJHANHez7xzYtGZA
zXAkZq_6D9xzdfHZ$|XXz+^3=a>mP-mFFC#%zMMSAtj982T!csa%lD=u*Zk%m+^X<d
zJ@ML!2e0?C`(H3Qt##+%PfhknbI&ygcRZZyvTLu9?=-gwcLWs*{WZnQT9PNnoA|hy
z7ij--FFs@wb&{<;(z3Aae|eU6VV2g(AIeLTuBw@D-n(Xj_hn}(-&@tPF`|XL&t3?P
zf11GY@!oCGrE`~t{}Q~t`C^|zQhV{L?!YwDn?WA)OFH*GJ`mi!F(%7+PL5l7!g~eb
zPakgo*ipt(72hf6c;le^>B_Fp0hbR(=-->3oqI&h{;Q0S{IU=E9or+`ap&z2dhzzE
z+49%kqScpKb-2R+YF~3*|0VF)j8{8ae1e<Le7-v~_Ekmca_tGv6n4q%=h^R|=yq+k
z;?AT1aqXEWE{MNMO7DE8Iq6r@!G1Nyznv@G@92LiyYaM9C#)s^tH42XPRFl%`BnNJ
znaMRL7VlTt_~L-k$3rDgd9J+jUB`C$mwG@{VMCIWW%i$FyTbU?9p$lCoo0E&SY2-G
zx{_YL==JZKt*M7&h0mX#Co&^*`nlPUu5a|4er~>8mga?P*`GPrUJPWue^4N2uh{ep
z4Ig);=k8z8lN)*L=gun=0}sz;J0oeiZRgq-dmDXkW=@|I`6E@m@Vt}U?EMCYxAHFA
zvT(B85OdvCvFEDm<6^g?Tf94_OjsbW=nmhim1%uO+vgqG<?Nq$FQTM<#>17bFVCM>
zRPni~%I4&gSrI3+*m8Lf7^+U0&$GhKW|dxW@ZIbAn@U6k{^j4O^ltCto6gh5Y$0BM
z^5AaIgbQ0UlR}I>i!}>***vP7U(&FdyXW48zS@lzb?&i@`rNL1K|5=1SIHU*<Z?6p
z6AwMtSERmp&AqKB?Ggi>9j=6mtoqd(w5Ls9_q~skan<2Hj(r-p=gsfWS$BMTgOzM<
zE$`#we%FiUY76viShytoUkOLu&8*+K-fm7N+Yf~O^ItWGgJI{hng#8elb=3iv5Tvj
zdv*7%^m_ukELohU<?=k<Sua?nn;<-8?%{X-8butJ_z&E_o&UYLx{&wbC5s$g>80Cl
z&e6Z~_15YW*)>WNETm_i^ZZ(|{K(?>m$wMUo9gBG|FK=Z=3To;bBKD&Je!y+Rb4xJ
z3N7ymxHn3jy7Xh}mF8~(G7emEhMVNrb{$9)O4LiNixy#GUcY!+p!-*ErG_atp8l}&
z?CZO}U{~AK6Sw9RIov<L>Uj43$5qx7m{fjmJ0?G)amsehPx03@c-X9F-aI;gdER1a
zUUU1_WR8{hzq)VC{Qm02lBcH=*Kr1|eJyKr?Si+!mHYhvl(LiaUR`Ew%J{i0pJVB&
zUE-?N3-;fw6E#xlef;2l_vO>K)7SiYRL-<3XyYr7r;5|X4H=~7U+ySv`6ZxS^!F0S
zOvyvXPMs<;+kcOB#eIj*f`aSiALj<{ZiqAc$s6syR#WKpig%tXzIaDYdh@`{S@v%-
z|GB;SiG2*F`dgnZx|~;A*Z4lI$U*(cH{l8fhD62i1<_Tntr!>^1R4|=7-E(SW^6o?
N{+kKZ3}A_j0sx0D2c`f3

literal 0
HcmV?d00001

-- 
2.52.0

Re: [PATCH v2 0/2] btrfs-progs: enhance detection on unknown keys in subvolumes

[David Sterba]

On Tue, Dec 16, 2025 at 07:53:46PM +1030, Qu Wenruo wrote:
> [CHANGELOG]
> v2:
> - Add a new test case
> 
> This is inspired by a real world bitflip corruption, where an INODE_REF
> is now 8 (an unknown key type), causing btrfs-check to freak out and the
> existing INODE_REF/DIR_ITEM/DIR_INDEX repair is not cutting this
> particular case for the original mode.
> 
> Lowmem mode is better, but for this particular image it's too large and
> lowmem is too slow to be practical.
> 
> As the first step, detect and report such unknown keys in subvolume
> trees as an error.
> 
> With a new test case for it.
> 
> In the long run we should allow btrfs-check --repair to delete such
> unknown keys.
> 
> Qu Wenruo (2):
>   btrfs-progs: enhance detection on unknown inode keys
>   btrfs-progs: add a test case for unknown keys in subvolume trees

Added to devel, thanks.