Skip to contentSkip to conversation

btrfs-progs: enhance detection on unknown keys in subvolumes

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

lore
Share & tools
lore

Qu Wenruo

author
#0 lore raw

v2 cover btrfs-progs: enhance detection on unknown keys in subvolumes

[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

author
#1 lore raw

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

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

---
 check/main.c        | 7 +++++++
 check/mode-lowmem.c | 5 +++--
 check/mode-lowmem.h | 1 +
 3 files changed, 11 insertions(+), 2 deletions(-)
check/main.c +7 -0
index db055ae194f8..96c7ef7d8261 100644
@@ -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;
 }
check/mode-lowmem.c +3 -2
index ea4d4017827f..8a4c5bc1e10d 100644
@@ -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;
 		}
 	}
 
check/mode-lowmem.h +1 -0
index cd0355465be9..ec199b4c8008 100644
@@ -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.
Signature · 1 line
2.52.0
author
#2 lore raw

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

In reply to 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.

---
 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
tests/fsck-tests/069-unknown-fs-tree-key/test.sh new file +14 -0
new file mode 100755
index 000000000000..ea4f04e284be
@@ -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
tests/fsck-tests/069-unknown-fs-tree-key/unknown_key_empty.img.xz new file binary +0 -0
new file mode 100644
index 0000000000000000000000000000000000000000..300a7cc92b7125d0309be6917195695610a0f549
GIT binary patch
Signature · 1 line
2.52.0
#3 lore raw
In reply to Qu Wenruo
Quoted 15 lines · 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.

Quoted 8 lines

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.