| 1 |
.\" Man page generated from reStructuredText |
| 2 |
.\" by the Docutils 0.22.4 manpage writer. |
| 3 |
. |
| 4 |
. |
| 5 |
.nr rst2man-indent-level 0 |
| 6 |
. |
| 7 |
.de1 rstReportMargin |
| 8 |
\\$1 \\n[an-margin] |
| 9 |
level \\n[rst2man-indent-level] |
| 10 |
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 11 |
- |
| 12 |
\\n[rst2man-indent0] |
| 13 |
\\n[rst2man-indent1] |
| 14 |
\\n[rst2man-indent2] |
| 15 |
.. |
| 16 |
.de1 INDENT |
| 17 |
.\" .rstReportMargin pre: |
| 18 |
. RS \\$1 |
| 19 |
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| 20 |
. nr rst2man-indent-level +1 |
| 21 |
.\" .rstReportMargin post: |
| 22 |
.. |
| 23 |
.de UNINDENT |
| 24 |
. RE |
| 25 |
.\" indent \\n[an-margin] |
| 26 |
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 27 |
.nr rst2man-indent-level -1 |
| 28 |
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 29 |
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| 30 |
.. |
| 31 |
.TH "BTRFS-RESCUE" "8" "May 10, 2026" "7.0" "BTRFS" |
| 32 |
.SH NAME |
| 33 |
btrfs-rescue \- recover a damaged btrfs filesystem |
| 34 |
.SH SYNOPSIS |
| 35 |
.sp |
| 36 |
\fBbtrfs rescue\fP <subcommand> <args> |
| 37 |
.SH DESCRIPTION |
| 38 |
.sp |
| 39 |
A set of commands that are targeting to fix a specific problem and may not |
| 40 |
suitable for :doc\(gabtrfs\-check\(ga. |
| 41 |
.sp |
| 42 |
\fBNote:\fP |
| 43 |
.INDENT 0.0 |
| 44 |
.INDENT 3.5 |
| 45 |
All the subcommands cannot handle an ongoing replace/balance, please finish/cancel |
| 46 |
the replace/balance before using this command. |
| 47 |
.UNINDENT |
| 48 |
.UNINDENT |
| 49 |
.SH SUBCOMMAND |
| 50 |
.INDENT 0.0 |
| 51 |
.TP |
| 52 |
.B chunk\-recover [options] <device> |
| 53 |
Recover the chunk tree by scanning the devices |
| 54 |
.sp |
| 55 |
\fBOptions\fP |
| 56 |
.INDENT 7.0 |
| 57 |
.TP |
| 58 |
.B \-y |
| 59 |
assume an answer of \fIyes\fP to all questions. |
| 60 |
.TP |
| 61 |
.B \-h |
| 62 |
help. |
| 63 |
.TP |
| 64 |
.B \-v |
| 65 |
(deprecated) alias for global \fI\-v\fP option |
| 66 |
.UNINDENT |
| 67 |
.UNINDENT |
| 68 |
.sp |
| 69 |
\fBNote:\fP |
| 70 |
.INDENT 0.0 |
| 71 |
.INDENT 3.5 |
| 72 |
Since \fBchunk\-recover\fP will scan the whole device, it will be very |
| 73 |
slow especially if executed on a large device. |
| 74 |
.UNINDENT |
| 75 |
.UNINDENT |
| 76 |
.INDENT 0.0 |
| 77 |
.TP |
| 78 |
.B fix\-device\-size <device> |
| 79 |
Fix device size and super block total bytes values that do not match. |
| 80 |
.sp |
| 81 |
Kernel 4.11 starts to check the device size more strictly and this might |
| 82 |
mismatch the stored value of total bytes. See the exact error message below. |
| 83 |
Newer kernel will refuse to mount the filesystem where the values do not match. |
| 84 |
This error is not fatal and can be fixed. This command will fix the device |
| 85 |
size values if possible. |
| 86 |
.INDENT 7.0 |
| 87 |
.INDENT 3.5 |
| 88 |
.sp |
| 89 |
.EX |
| 90 |
BTRFS error (device sdb): super_total_bytes 92017859088384 mismatch with fs_devices total_rw_bytes 92017859094528 |
| 91 |
.EE |
| 92 |
.UNINDENT |
| 93 |
.UNINDENT |
| 94 |
.sp |
| 95 |
The mismatch may also exhibit as a kernel warning: |
| 96 |
.INDENT 7.0 |
| 97 |
.INDENT 3.5 |
| 98 |
.sp |
| 99 |
.EX |
| 100 |
WARNING: CPU: 3 PID: 439 at fs/btrfs/ctree.h:1559 btrfs_update_device+0x1c5/0x1d0 [btrfs] |
| 101 |
.EE |
| 102 |
.UNINDENT |
| 103 |
.UNINDENT |
| 104 |
.TP |
| 105 |
.B fix\-data\-checksum <device> |
| 106 |
Selectively fix data checksum mismatch. |
| 107 |
.sp |
| 108 |
There is a long existing problem that if a user space program is doing |
| 109 |
direct IO and modifies the buffer before the write back finished, it |
| 110 |
can lead to data checksum mismatches. |
| 111 |
.sp |
| 112 |
This problem is known but not fixed until upstream release v6.15 |
| 113 |
(backported to older kernels). So it\(aqs possible to hit false data |
| 114 |
checksum mismatch for any long running btrfs. |
| 115 |
.sp |
| 116 |
In that case this program can be utilized to repair such problem. |
| 117 |
.sp |
| 118 |
\fBOptions\fP |
| 119 |
.INDENT 7.0 |
| 120 |
.TP |
| 121 |
.B \-r|\-\-readonly |
| 122 |
readonly mode, only scan for and report data checksum mismatches, |
| 123 |
do not repair |
| 124 |
.TP |
| 125 |
.B \-i|\-\-interactive |
| 126 |
interactive mode, ask for how to repair, ignore the errors by default |
| 127 |
.TP |
| 128 |
.B \-m|\-\-mirror <num> |
| 129 |
use specified mirror to update the checksum item for all corrupted blocks. |
| 130 |
.sp |
| 131 |
The value must be >= 1, and if the corrupted block has fewer mirrors than |
| 132 |
the value, the mirror number will be \fBnum % (num_mirrors + 1)\fP\&. |
| 133 |
.UNINDENT |
| 134 |
.UNINDENT |
| 135 |
.INDENT 0.0 |
| 136 |
.TP |
| 137 |
.B clear\-ino\-cache <device> |
| 138 |
Remove leftover items pertaining to the deprecated \fIinode number cache\fP feature. |
| 139 |
.sp |
| 140 |
The feature enabled by mount option \fIinode_cache\fP has been completely |
| 141 |
removed in 5.11 kernel. |
| 142 |
.TP |
| 143 |
.B clear\-space\-cache <v1|v2> <device> |
| 144 |
Completely remove the on\-disk data of free space cache of given version. |
| 145 |
.sp |
| 146 |
Especially for v1 free space cache, \fIclear_cache\fP mount option would only |
| 147 |
remove the cache for updated block groups, the remaining would not be removed. |
| 148 |
Thus this command is provided to manually clear the free space cache. |
| 149 |
.UNINDENT |
| 150 |
.INDENT 0.0 |
| 151 |
.TP |
| 152 |
.B clear\-uuid\-tree <device> |
| 153 |
Clear the UUID tree, so that kernel can regenerate it at next read\-write |
| 154 |
mount. |
| 155 |
.sp |
| 156 |
Since kernel v4.16 there are more sanity check performed, and sometimes |
| 157 |
non\-critical trees like UUID tree can cause problems and reject the mount. |
| 158 |
In such case, clearing UUID tree may make the filesystem to be mountable again |
| 159 |
without much risk as it\(aqs built from other trees. |
| 160 |
See also mount option rescan_uuid_tree (in btrfs\-man5) \%<btrfs-man5//#\:mount-option-rescan-uuid-tree>\&. |
| 161 |
.TP |
| 162 |
.B super\-recover [options] <device> |
| 163 |
Recover bad superblocks from good copies. |
| 164 |
.sp |
| 165 |
\fBOptions\fP |
| 166 |
.INDENT 7.0 |
| 167 |
.TP |
| 168 |
.B \-y |
| 169 |
assume an answer of \fIyes\fP to all questions. |
| 170 |
.TP |
| 171 |
.B \-v |
| 172 |
(deprecated) alias for global \fI\-v\fP option |
| 173 |
.UNINDENT |
| 174 |
.TP |
| 175 |
.B zero\-log <device> |
| 176 |
Clear the filesystem log tree. |
| 177 |
.sp |
| 178 |
This command will clear the filesystem log tree. This may fix a specific |
| 179 |
set of problem when the filesystem mount fails during log replay. See below |
| 180 |
for sample stack traces that may show up in system log. |
| 181 |
.sp |
| 182 |
\fBNote:\fP |
| 183 |
.INDENT 7.0 |
| 184 |
.INDENT 3.5 |
| 185 |
Clearing the log may lead to loss of changes that were made |
| 186 |
since the last transaction commit. This may be up to 30 seconds |
| 187 |
(default commit period) or less if the commit was implied by |
| 188 |
other filesystem activity. |
| 189 |
.UNINDENT |
| 190 |
.UNINDENT |
| 191 |
.sp |
| 192 |
One can determine whether \fBzero\-log\fP is needed according to the kernel |
| 193 |
backtrace: |
| 194 |
.INDENT 7.0 |
| 195 |
.INDENT 3.5 |
| 196 |
.sp |
| 197 |
.EX |
| 198 |
? replay_one_dir_item+0xb5/0xb5 [btrfs] |
| 199 |
? walk_log_tree+0x9c/0x19d [btrfs] |
| 200 |
? btrfs_read_fs_root_no_radix+0x169/0x1a1 [btrfs] |
| 201 |
? btrfs_recover_log_trees+0x195/0x29c [btrfs] |
| 202 |
? replay_one_dir_item+0xb5/0xb5 [btrfs] |
| 203 |
? btree_read_extent_buffer_pages+0x76/0xbc [btrfs] |
| 204 |
? open_ctree+0xff6/0x132c [btrfs] |
| 205 |
.EE |
| 206 |
.UNINDENT |
| 207 |
.UNINDENT |
| 208 |
.sp |
| 209 |
If the errors are like above, then \fBzero\-log\fP should be used to clear |
| 210 |
the log and the filesystem may be mounted normally again. The keywords to look |
| 211 |
for are \(aqopen_ctree\(aq which says that it\(aqs during mount and function names |
| 212 |
that contain \fIreplay\fP, \fIrecover\fP or \fIlog_tree\fP\&. |
| 213 |
.UNINDENT |
| 214 |
.SH EXIT STATUS |
| 215 |
.sp |
| 216 |
\fBbtrfs rescue\fP returns a zero exit status if it succeeds. Non zero is |
| 217 |
returned in case of failure. |
| 218 |
.SH AVAILABILITY |
| 219 |
.sp |
| 220 |
\fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at |
| 221 |
\%<https://\:btrfs\:.readthedocs\:.io>\&. |
| 222 |
.SH SEE ALSO |
| 223 |
.sp |
| 224 |
btrfs\-check(8) \%<>, |
| 225 |
btrfs\-scrub(8) \%<>, |
| 226 |
mkfs.btrfs(8) \%<> |
| 227 |
.\" End of generated man page. |