xfs_repair(8)

✨ xfs_repair(8) ✨

xfs_repair(8) 🎀 from the System Manager's Manual, bestie, this is your official guide 💖

🌸 NAME 🌸

xfs_repair - repair an XFS filesystem 🔧✨

🦋 SYNOPSIS 🦋

xfs_repair [ -dfLPv ] [ -n | -e ] [ -m maxmem ] [ -c subopt=value ] [ -o
subopt[=value] ] [ -t interval ] [ -l logdev ] [ -r rtdev ] device
xfs_repair -V

💜 DESCRIPTION 💜

okay so xfs_repair is the tool that fixes up corrupt or damaged XFS filesystems (go peek at xfs(5) if you want the deep lore) 🫶 You point it at the filesystem with the device argument, which should be the device name of the disk partition or volume holding the filesystem. If you hand it a block device, xfs_repair will try to find the raw device behind it and use that one instead 🧚

Now, the big rule, periodt: the filesystem you're repairing must be unmounted 😭 If it isn't, the result could be inconsistent or corrupt, and nobody wants that bestie 💀

🎀 OPTIONS 🎀

• -f — Tells xfs_repair that the filesystem image lives in a regular file at device instead of on a real disk 📁 (see the mkfs.xfs -d file option). This happens when someone made an image copy of a filesystem or wrote it into an ordinary file. It also means any external log or realtime section is in an ordinary file too 🌈
• -L — Force Log Zeroing 💀 This makes xfs_repair zero the log even if it's dirty (aka it has metadata changes waiting to be written). Be warned, the filesystem will probably look corrupt afterwards, and you can lose user files and/or data 😭 Check the DIRTY LOGS section for the full tea.
• -l logdev — Points to the device special file where the filesystem's external log lives 📜 This only matters for filesystems that use an external log. See the mkfs.xfs -l option, and check xfs(5) for the full scoop on the XFS log ✨
• -r rtdev — Points to the device special file where the filesystem's realtime section lives 🍓 This is only for filesystems that actually use a realtime section. See the mkfs.xfs -r option, and peep xfs(5) for a detailed description of the XFS realtime section 💅
• -n — No modify mode 👀 xfs_repair scans the filesystem and tells you what repairs would have been made, but it won't touch a single thing. Can't be used together with -e 🙅‍♀️
• -P — Disables prefetching of inode and directory blocks 🧸 Use this if xfs_repair seems stuck and stops making progress. The good news is that interrupting a stuck xfs_repair is safe 🫶
• -m maxmem — Sets the approximate maximum amount of memory, in megabytes, that xfs_repair can use 🧠 By default, xfs_repair has its own internal block cache that scales out up to the lesser of the process's virtual address limit or about 75% of the system's physical RAM. This option overrides those limits 💜

NOTE: These memory limits are only approximate, so xfs_repair may end up using more than the number you gave it 🙈

• -c subopt=value — Changes filesystem parameters ⚙️ For info on changing those, check out xfs_admin(8) 🦋
• -o subopt[=value] — Overrides what the program might conclude about the filesystem if it were left to its own devices 👑 The suboptions you can use are:
  • bhash=bhashsize — Overrides the default buffer cache hash size 🫧 The total number of buffer cache entries is capped at 8 times this amount. By default, the size is set to use up the remainder of 75% of the system's physical RAM size 💖
  • ag_stride=ags_per_concat_unit — Creates extra processing threads so AGs that span multiple concat units can be processed in parallel 🧵 This can seriously cut down repair times on concat based filesystems 🔥
  • force_geometry — Checks the filesystem even if its geometry information couldn't be validated 🙈 Geometry info can't be validated if only a single allocation group exists (so there's no backup superblock available), or if there are two allocation groups and the two superblocks don't agree on the geometry. Only use this if you validated the geometry yourself and know exactly what you're doing 😤 If in doubt, run in no modify mode (-n) first.
  • noquota — Doesn't validate quota counters at all 🧾 Quotacheck will run during the next mount to recalculate all the values 🌸
• -t interval — Changes the reporting interval, specified in seconds ⏱️ On long runs, xfs_repair outputs its progress every 15 minutes. Reporting is only activated when ag_stride is enabled 🐣
• -v — Verbose output 📢 You can repeat it to crank the verbosity even higher 🔊
• -d — Repair dangerously 😈 This lets xfs_repair repair an XFS filesystem that's mounted read only. It's typically done on a root filesystem from single user mode, and then you reboot immediately after 🙈

This one is risky business, bestie. Only do it the way described above 💀

• -e — If any metadata corruption got repaired, the exit status is 4 instead of the usual 0 🚦 This can't be used together with -n 🙅‍♀️
• -V — Prints the version number and exits 🏷️

💖 Checks Performed 💖

slay, before it even looks at the filesystem, xfs_repair tests whether the crc32c checksum implementation is correct 🧪 If that test fails, the program aborts, so you'll know something's sus right away 🚨

Here's the list of inconsistencies it can fix:

1. Inode and inode blockmap (addressing) checks 🦋 Bad magic number in an inode, bad magic numbers in inode blockmap blocks, extents out of order, the wrong number of records in inode blockmap blocks, blocks claimed that aren't in a legal data area of the filesystem, and blocks claimed by more than one inode 😭
2. Inode allocation map checks 🗺️ Bad magic number in inode map blocks, inode state (free or in-use) in the map not matching the state in the inode, inodes referenced by the filesystem that don't show up in the inode allocation map, and an inode allocation map referencing blocks that don't seem to contain inodes 🙃
3. Size checks 📏 Number of blocks claimed by an inode not matching its size, directory size not being block aligned, and inode size not being consistent with the inode format 🧸
4. Directory checks 📂 Bad magic numbers in directory blocks, the wrong number of entries in a directory block, bad freespace info in a directory leaf block, an entry pointing to an unallocated (free) or out of range inode, overlapping entries, missing or incorrect dot and dotdot entries, entries out of hashvalue order, incorrect internal directory pointers, and a directory type that doesn't match the inode format and size 🌈
5. Pathname checks 🛤️ Files or directories not referenced by a pathname starting from the filesystem root, and illegal pathname components 🙅‍♀️
6. Link count checks 🔗 Link counts that don't agree with the number of directory references to the inode 🧮
7. Freemap checks 🧺 Blocks claimed free by the freemap but also claimed by an inode, and blocks unclaimed by any inode that don't show up in the freemap 🫠
8. Super Block checks 👑 Total free block and/or free i-node count being incorrect, filesystem geometry being inconsistent, and secondary and primary superblocks contradicting each other 💀

Orphaned files and directories (allocated and in-use, but unreferenced) get reconnected by being placed in the lost+found directory 🧚 The name they're given is the inode number 🔢

🧯 Disk Errors 🧯

xfs_repair aborts on most disk I/O errors 😱 So if you're trying to repair a filesystem that got damaged by a disk drive failure, make sure every block in the filesystem is readable and writable before you run xfs_repair 🫶 One method is using dd(8) to copy the data onto a good disk 💾

📁 lost+found 📁

The lost+found directory doesn't have to exist already 🥰 If it's missing and needed, it gets created automatically ✨ If it's already there, it gets checked for consistency, and if it's valid it'll be used for additional orphaned files 🌸 Invalid lost+found directories get removed and recreated 🙅‍♀️ Existing files in a valid lost+found are never removed or renamed, so your stuff stays safe 🫶

👑 Corrupted Superblocks 👑

XFS has both primary and secondary superblocks 🧠 xfs_repair uses the info in the primary superblock to automatically find the secondary superblocks and validate the primary against them before moving on 🔍 If the primary is too corrupted to be useful for finding the secondary superblocks, the program scans the filesystem until it finds and validates some secondary superblocks 🕵️‍♀️ At that point, it generates a primary superblock 🦸‍♀️

🧾 Quotas 🧾

If quotas are in use, xfs_repair might clear some or all of the filesystem quota information 😬 If that happens, the program issues a warning just before it terminates 🚨 If all the quota information gets lost, quotas are disabled and the program issues a warning to that effect 💔

Also, xfs_repair doesn't check the validity of quota limits 🙈 So it's recommended that you check the quota limit information manually after running xfs_repair 📝 Space usage info is automatically regenerated the next time the filesystem is mounted with quotas turned on, so that next quota mount may take some time ⏳

🔍 DIAGNOSTICS 🔍

okay so xfs_repair talks to you the whole time it's working ✨ it tells you what's looking sus, or what it fixed. Most messages only make sense if you already know the filesystem's insides, so I'm highlighting the common ones 💅 Also, the wording changes a little in no-modify mode (-n) because nothing gets touched on disk 🙈 In that mode it tells you what it would do if you ran it without -n.

disconnected inode ino, moving to lost+found

Inode ino wasn't hooked up to the directory tree anymore, so xfs_repair reconnected it inside lost+found 🧚 It gets named after its inode number (ino). If there's no lost+found directory yet, it makes one for you automatically 🫶

disconnected dir inode ino, moving to lost+found

Same drama, but this time it's a directory inode 📁 Any children it has stay attached to it, so they get reconnected automatically when the directory does ✨

imap claims in-use inode ino is free, correcting imap

The inode allocation map says inode ino is free, but when xfs_repair checks the inode it looks like it might be in use (even if it's disconnected). So it fixes the allocation map 🛠️

imap claims free inode ino is in use, correcting imap

Flip side: the allocation map says inode ino is in use, but the inode itself says it's free. It updates the allocation map to match 💜

resetting inode ino nlinks from x to y

xfs_repair noticed the number of valid directory entries pointing at inode ino doesn't match the link count stored in the inode, so it corrected the count 🎀

fork-type fork in ino ino claims used block bno

Inode ino is trying to claim block bno, but that block is already claimed by another inode or by the filesystem's own metadata 🙃 The fork-type will be either data or attr, which tells you whether the problem is in the regular data part of the inode or the XFS attributes part. If it's a real-time (rt) inode, the message says so. Any inode claiming blocks the filesystem already uses gets deleted, and if two or more inodes claim the same block, they all get deleted 💀

fork-type fork in ino ino claims dup extent ...

Inode ino has a block sitting in an extent that's known to be claimed more than once 👀 The message gives you the offset in the inode, plus the start and length of the extent. It reads a little differently if the inode is a real-time (rt) inode, since the extent is then a real-time (rt) extent 🌸

inode ino - bad extent ...

An extent record in inode ino's blockmap is claiming blocks outside the legal range of the filesystem 😭 The message tells you the start, end, and file offset of that extent. It's worded a bit differently if the extent is a real-time (rt) extent ✨

bad fork-type fork in inode ino

Something is structurally wrong or inconsistent in the data structures that map offsets to filesystem blocks 🥲

cleared inode ino

Something was wrong with inode ino that couldn't be fixed, so xfs_repair freed it 🗑️ This usually happens when the inode claims blocks someone else is using, or when the inode itself is badly corrupted. Usually a few messages about why show up right before this one.

bad attribute fork in inode ino, clearing attr fork

The attribute fork of inode ino (the part that stores XFS attributes) had a problem, so xfs_repair reset it 💔 That means all attributes on that inode are lost.

correcting nextents for inode ino, was x - counted y

xfs_repair found that the number of extents used to store the inode's data was wrong, so it fixed the number 🔧 If the miscount is about attribute storage, the message says nextents anyway, which is a little confusing but that's the vibe 🙈

entry name in dir dir_ino not consistent with .. value (xxxx) in dir ino ino, junking entry name in directory inode dir_ino

Directory inode dir_ino has an entry name pointing at directory inode ino. But the .. entry inside directory ino doesn't point back at dir_ino, so the entry name in dir_ino gets deleted 🗑️ If directory ino ends up disconnected because of this, it gets moved to lost+found later on.

entry name in dir dir_ino references already connected dir ino ino, junking entry name in directory inode dir_ino

The entry name in dir_ino points at directory inode ino, which is already a child of some other directory. So the entry is invalid and gets deleted 🙅‍♀️ This message is for a small directory. If it were a large directory, the ending would say will clear entry instead.

entry references free inode ino in directory dir_ino, will clear entry

An entry in directory inode dir_ino points at inode ino, which is known to be free. The entry is invalid, so it gets deleted 🧹 This message is for a large directory. In a small directory it would say junking entry ... instead.

---

🚦 EXIT STATUS 🚦

Here's the status code breakdown, bestie 🫶

xfs_repair -n (no-modify mode) returns 1 if it detected filesystem corruption, and 0 if it didn't.

Without -n, xfs_repair returns 0 if it finishes without problems, unless you used the -e flag. With -e, it returns 4 when it found an issue with the filesystem that it could fix ✨

If xfs_repair hits a runtime error while it's working, it returns 1. In that case, you should restart xfs_repair 🔁

If xfs_repair can't continue because of a dirty log, it returns 2. See below for the dirty log tea ☕

---

📜 DIRTY LOGS 📜

Because of how the XFS log is designed, a dirty log can only be replayed by the kernel, on a machine with the same CPU architecture as the one that wrote to the log 🧠 xfs_repair can't replay a dirty log, so it exits with status code 2 when it spots one.

In that situation, you can replay the log by mounting and then immediately unmounting the filesystem on the same class of machine that crashed 🔄 Make sure that machine's hardware is reliable before you replay anything so you don't make the problems worse 🫠

If mounting fails, you can erase the log by running xfs_repair with the -L option.

Big warning, bestie: every metadata update that was in progress when the crash happened will be lost, and that can cause serious filesystem damage 💀 This is a last-resort move only. Please don't reach for it first.

---

🐛 BUGS 🐛

The filesystem you're checking and repairing has to have been unmounted cleanly with normal system admin procedures (the umount(8) command or a system shutdown), not because of a crash or system reset 🙅‍♀️ If it wasn't unmounted cleanly, mount it and unmount it cleanly before you run xfs_repair.

xfs_repair doesn't do a thorough job on XFS extended attributes 😬 The attribute fork's structure will be consistent, but only attribute forks small enough to fit inside an inode actually get checked. This limitation will be fixed in the future 🔮

The no-modify mode (-n option) isn't completely accurate either. It doesn't catch inconsistencies in the freespace and inode maps, especially lost blocks or subtly corrupted maps (trees) 🌳

No-modify mode can also spit out repeated warnings about the same problems, because it can't fix anything as it goes 🔁

If a filesystem won't repair, you can generate a metadump image with xfs_metadump(8) and send it to an XFS maintainer, so they can analyse it and improve and/or fix xfs_repair 💌

---

🔗 SEE ALSO 🔗

• dd(1)
• mkfs.xfs(8)
• umount(8)
• xfs_admin(8)
• xfs_metadump(8)
• xfs(5)

That's the whole xfs_repair(8) page, bestie 🎀✨ Go be a filesystem hero 🦋💅