{ "mode": "man", "parameter": "xfs_repair", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/xfs_repair/8/json", "generated": "2026-10-04T08:30:58Z", "synopsis": "xfsrepair [ -dfLPv ] [ -n | -e ] [ -m maxmem ] [ -c subopt=value ] [ -o subopt[=value] ] [", "sections": { "NAME": { "content": "xfsrepair - repair an XFS filesystem\n", "subsections": [] }, "SYNOPSIS": { "content": "xfsrepair [ -dfLPv ] [ -n | -e ] [ -m maxmem ] [ -c subopt=value ] [ -o subopt[=value] ] [", "subsections": [ { "name": "-t _ -l _ -r _", "content": "", "flag": "-r" }, { "name": "xfs_repair -V", "content": "" } ] }, "DESCRIPTION": { "content": "xfsrepair repairs corrupt or damaged XFS filesystems (see xfs(5)). The filesystem is speci‐\nfied using the device argument which should be the device name of the disk partition or vol‐\nume containing the filesystem. If given the name of a block device, xfsrepair will attempt\nto find the raw device associated with the specified block device and will use the raw device\ninstead.\n\nRegardless, the filesystem to be repaired must be unmounted, otherwise, the resulting\nfilesystem may be inconsistent or corrupt.\n", "subsections": [] }, "OPTIONS": { "content": "", "subsections": [ { "name": "-f", "content": "vice (see the mkfs.xfs -d file option). This might happen if an image copy of a\nfilesystem has been copied or written into an ordinary file. This option implies that\nany external log or realtime section is also in an ordinary file.\n", "flag": "-f" }, { "name": "-L", "content": "metadata changes). When using this option the filesystem will likely appear to be\ncorrupt, and can cause the loss of user files and/or data. See the DIRTY LOGS section\nfor more information.\n", "flag": "-L" }, { "name": "-l _", "content": "Specifies the device special file where the filesystem's external log resides. Only\nfor those filesystems which use an external log. See the mkfs.xfs -l option, and re‐\nfer to xfs(5) for a detailed description of the XFS log.\n", "flag": "-l" }, { "name": "-r _", "content": "Specifies the device special file where the filesystem's realtime section resides.\nOnly for those filesystems which use a realtime section. See the mkfs.xfs -r option,\nand refer to xfs(5) for a detailed description of the XFS realtime section.\n", "flag": "-r" }, { "name": "-n", "content": "only scan the filesystem and indicate what repairs would have been made. This option\ncannot be used together with -e.\n", "flag": "-n" }, { "name": "-P", "content": "pair gets stuck and stops proceeding. Interrupting a stuck xfsrepair is safe.\n", "flag": "-P" }, { "name": "-m _", "content": "Specifies the approximate maximum amount of memory, in megabytes, to use for xfsre‐\npair. xfsrepair has its own internal block cache which will scale out up to the\nlesser of the process's virtual address limit or about 75% of the system's physical\nRAM. This option overrides these limits.\n\nNOTE: These memory limits are only approximate and may use more than the specified\nlimit.\n", "flag": "-m" }, { "name": "-c _", "content": "Change filesystem parameters. Refer to xfsadmin(8) for information on changing\nfilesystem parameters.\n", "flag": "-c" }, { "name": "-o _", "content": "Override what the program might conclude about the filesystem if left to its own de‐\nvices.\n\nThe suboptions supported are:\n\nbhash=bhashsize\noverrides the default buffer cache hash size. The total number of buffer\ncache entries are limited to 8 times this amount. The default size is set to\nuse up the remainder of 75% of the system's physical RAM size.\n\nagstride=agsperconcatunit\nThis creates additional processing threads to parallel process AGs that span\nmultiple concat units. This can significantly reduce repair times on concat\nbased filesystems.\n\nforcegeometry\nCheck the filesystem even if geometry information could not be validated.\nGeometry information can not be validated if only a single allocation group\nexists and thus we do not have a backup superblock available, or if there\nare two allocation groups and the two superblocks do not agree on the\nfilesystem geometry. Only use this option if you validated the geometry\nyourself and know what you are doing. If In doubt run in no modify mode\nfirst.\n\nnoquota\nDon't validate quota counters at all. Quotacheck will be run during the\nnext mount to recalculate all values.\n", "flag": "-o" }, { "name": "-t interval", "content": "Modify reporting interval, specified in seconds. During long runs xfsrepair outputs\nits progress every 15 minutes. Reporting is only activated when agstride is enabled.\n", "flag": "-t" }, { "name": "-v", "content": "", "flag": "-v" }, { "name": "-d", "content": "This is typically done on a root filesystem from single user mode, immediately fol‐\nlowed by a reboot.\n", "flag": "-d" }, { "name": "-e", "content": "0. This option cannot be used together with -n.\n", "flag": "-e" }, { "name": "-V", "content": "", "flag": "-V" }, { "name": "Checks Performed", "content": "The correctness of the crc32c checksum implementation will be tested before examining the\nfilesystem. If the test fails, the program will abort.\n\nInconsistencies corrected include the following:\n\n1. Inode and inode blockmap (addressing) checks: bad magic number in inode, bad magic\nnumbers in inode blockmap blocks, extents out of order, incorrect number of records in\ninode blockmap blocks, blocks claimed that are not in a legal data area of the\nfilesystem, blocks that are claimed by more than one inode.\n\n2. Inode allocation map checks: bad magic number in inode map blocks, inode state as in‐\ndicated by map (free or in-use) inconsistent with state indicated by the inode, inodes\nreferenced by the filesystem that do not appear in the inode allocation map, inode al‐\nlocation map referencing blocks that do not appear to contain inodes.\n\n3. Size checks: number of blocks claimed by inode inconsistent with inode size, directory\nsize not block aligned, inode size not consistent with inode format.\n\n4. Directory checks: bad magic numbers in directory blocks, incorrect number of entries\nin a directory block, bad freespace information in a directory leaf block, entry\npointing to an unallocated (free) or out of range inode, overlapping entries, missing\nor incorrect dot and dotdot entries, entries out of hashvalue order, incorrect inter‐\nnal directory pointers, directory type not consistent with inode format and size.\n\n5. Pathname checks: files or directories not referenced by a pathname starting from the\nfilesystem root, illegal pathname components.\n\n6. Link count checks: link counts that do not agree with the number of directory refer‐\nences to the inode.\n\n7. Freemap checks: blocks claimed free by the freemap but also claimed by an inode,\nblocks unclaimed by any inode but not appearing in the freemap.\n\n8. Super Block checks: total free block and/or free i-node count incorrect, filesystem\ngeometry inconsistent, secondary and primary superblocks contradictory.\n\nOrphaned files and directories (allocated, in-use but unreferenced) are reconnected by plac‐\ning them in the lost+found directory. The name assigned is the inode number.\n" }, { "name": "Disk Errors", "content": "xfsrepair aborts on most disk I/O errors. Therefore, if you are trying to repair a filesys‐\ntem that was damaged due to a disk drive failure, steps should be taken to ensure that all\nblocks in the filesystem are readable and writable before attempting to use xfsrepair to re‐\npair the filesystem. A possible method is using dd(8) to copy the data onto a good disk.\n" }, { "name": "lost+found", "content": "The directory lost+found does not have to already exist in the filesystem being repaired. If\nthe directory does not exist, it is automatically created if required. If it already exists,\nit will be checked for consistency and if valid will be used for additional orphaned files.\nInvalid lost+found directories are removed and recreated. Existing files in a valid\nlost+found are not removed or renamed.\n" }, { "name": "Corrupted Superblocks", "content": "XFS has both primary and secondary superblocks. xfsrepair uses information in the primary\nsuperblock to automatically find and validate the primary superblock against the secondary\nsuperblocks before proceeding. Should the primary be too corrupted to be useful in locating\nthe secondary superblocks, the program scans the filesystem until it finds and validates some\nsecondary superblocks. At that point, it generates a primary superblock.\n" }, { "name": "Quotas", "content": "If quotas are in use, it is possible that xfsrepair will clear some or all of the filesystem\nquota information. If so, the program issues a warning just before it terminates. If all\nquota information is lost, quotas are disabled and the program issues a warning to that ef‐\nfect.\n\nNote that xfsrepair does not check the validity of quota limits. It is recommended that you\ncheck the quota limit information manually after xfsrepair. Also, space usage information\nis automatically regenerated the next time the filesystem is mounted with quotas turned on,\nso the next quota mount of the filesystem may take some time.\n" } ] }, "DIAGNOSTICS": { "content": "xfsrepair issues informative messages as it proceeds indicating what it has found that is\nabnormal or any corrective action that it has taken. Most of the messages are completely un‐\nderstandable only to those who are knowledgeable about the structure of the filesystem. Some\nof the more common messages are explained here. Note that the language of the messages is\nslightly different if xfsrepair is run in no-modify mode because the program is not changing\nanything on disk. No-modify mode indicates what it would do to repair the filesystem if run\nwithout the no-modify flag.\n\ndisconnected inode ino, moving to lost+found\n\nAn inode numbered ino was not connected to the filesystem directory tree and was re‐\nconnected to the lost+found directory. The inode is assigned the name of its inode\nnumber (ino). If a lost+found directory does not exist, it is automatically created.\n\ndisconnected dir inode ino, moving to lost+found\n\nAs above only the inode is a directory inode. If a directory inode is attached to\nlost+found, all of its children (if any) stay attached to the directory and therefore\nget automatically reconnected when the directory is reconnected.\n\nimap claims in-use inode ino is free, correcting imap\n\nThe inode allocation map thinks that inode ino is free whereas examination of the in‐\node indicates that the inode may be in use (although it may be disconnected). The\nprogram updates the inode allocation map.\n\nimap claims free inode ino is in use, correcting imap\n\nThe inode allocation map thinks that inode ino is in use whereas examination of the\ninode indicates that the inode is not in use and therefore is free. The program up‐\ndates the inode allocation map.\n\nresetting inode ino nlinks from x to y\n\nThe program detected a mismatch between the number of valid directory entries refer‐\nencing inode ino and the number of references recorded in the inode and corrected the\nthe number in the inode.\n\nfork-type fork in ino ino claims used block bno\n\nInode ino claims a block bno that is used (claimed) by either another inode or the\nfilesystem itself for metadata storage. The fork-type is either data or attr indicat‐\ning whether the problem lies in the portion of the inode that tracks regular data or\nthe portion of the inode that stores XFS attributes. If the inode is a real-time (rt)\ninode, the message says so. Any inode that claims blocks used by the filesystem is\ndeleted. If two or more inodes claim the same block, they are both deleted.\n\nfork-type fork in ino ino claims dup extent ...\n\nInode ino claims a block in an extent known to be claimed more than once. The offset\nin the inode, start and length of the extent is given. The message is slightly dif‐\nferent if the inode is a real-time (rt) inode and the extent is therefore a real-time\n(rt) extent.\n\ninode ino - bad extent ...\n\nAn extent record in the blockmap of inode ino claims blocks that are out of the legal\nrange of the filesystem. The message supplies the start, end, and file offset of the\nextent. The message is slightly different if the extent is a real-time (rt) extent.\n\nbad fork-type fork in inode ino\n\nThere was something structurally wrong or inconsistent with the data structures that\nmap offsets to filesystem blocks.\n\ncleared inode ino\n\nThere was something wrong with the inode that was uncorrectable so the program freed\nthe inode. This usually happens because the inode claims blocks that are used by\nsomething else or the inode itself is badly corrupted. Typically, this message is pre‐\nceded by one or more messages indicating why the inode needed to be cleared.\n\nbad attribute fork in inode ino, clearing attr fork\n\nThere was something wrong with the portion of the inode that stores XFS attributes\n(the attribute fork) so the program reset the attribute fork. As a result of this,\nall attributes on that inode are lost.\n\ncorrecting nextents for inode ino, was x - counted y\n\nThe program found that the number of extents used to store the data in the inode is\nwrong and corrected the number. The message refers to nextents if the count is wrong\non the number of extents used to store attribute information.\n\nentry name in dir dirino not consistent with .. value (xxxx) in dir ino ino, junking entry\nname in directory inode dirino\n\nThe entry name in directory inode dirino references a directory inode ino. However,\nthe .. entry in directory ino does not point back to directory dirino, so the program\ndeletes the entry name in directory inode dirino. If the directory inode ino winds\nup becoming a disconnected inode as a result of this, it is moved to lost+found later.\n\nentry name in dir dirino references already connected dir ino ino, junking entry name in di‐\nrectory inode dirino\n\nThe entry name in directory inode dirino points to a directory inode ino that is\nknown to be a child of another directory. Therefore, the entry is invalid and is\ndeleted. This message refers to an entry in a small directory. If this were a large\ndirectory, the last phrase would read \"will clear entry\".\n\nentry references free inode ino in directory dirino, will clear entry\n\nAn entry in directory inode dirino references an inode ino that is known to be free.\nThe entry is therefore invalid and is deleted. This message refers to a large direc‐\ntory. If the directory were small, the message would read \"junking entry ...\".\n", "subsections": [] }, "EXIT STATUS": { "content": "xfsrepair -n (no modify mode) will return a status of 1 if filesystem corruption was de‐\ntected and 0 if no filesystem corruption was detected. xfsrepair run without the -n option\nwill always return a status code of 0 if it completes without problems, unless the flag -e is\nused. If it is used, then status 4 is reported when any issue with the filesystem was found,\nbut could be fixed. If a runtime error is encountered during operation, it will return a sta‐\ntus of 1. In this case, xfsrepair should be restarted. If xfsrepair is unable to proceed\ndue to a dirty log, it will return a status of 2. See below.\n", "subsections": [] }, "DIRTY LOGS": { "content": "Due to the design of the XFS log, a dirty log can only be replayed by the kernel, on a ma‐\nchine having the same CPU architecture as the machine which was writing to the log. xfsre‐\npair cannot replay a dirty log and will exit with a status code of 2 when it detects a dirty\nlog.\n\nIn this situation, the log can be replayed by mounting and immediately unmounting the\nfilesystem on the same class of machine that crashed. Please make sure that the machine's\nhardware is reliable before replaying to avoid compounding the problems.\n\nIf mounting fails, the log can be erased by running xfsrepair with the -L option. All meta‐\ndata updates in progress at the time of the crash will be lost, which may cause significant\nfilesystem damage. This should only be used as a last resort.\n", "subsections": [] }, "BUGS": { "content": "The filesystem to be checked and repaired must have been unmounted cleanly using normal sys‐\ntem administration procedures (the umount(8) command or system shutdown), not as a result of\na crash or system reset. If the filesystem has not been unmounted cleanly, mount it and un‐\nmount it cleanly before running xfsrepair.\n\nxfsrepair does not do a thorough job on XFS extended attributes. The structure of the at‐\ntribute fork will be consistent, but only the contents of attribute forks that will fit into\nan inode are checked. This limitation will be fixed in the future.\n\nThe no-modify mode (-n option) is not completely accurate. It does not catch inconsistencies\nin the freespace and inode maps, particularly lost blocks or subtly corrupted maps (trees).\n\nThe no-modify mode can generate repeated warnings about the same problems because it cannot\nfix the problems as they are encountered.\n\nIf a filesystem fails to be repaired, a metadump image can be generated with xfsmetadump(8)\nand be sent to an XFS maintainer to be analysed and xfsrepair fixed and/or improved.\n", "subsections": [] }, "SEE ALSO": { "content": "dd(1), mkfs.xfs(8), umount(8), xfsadmin(8), xfsmetadump(8), xfs(5).\n\nxfsrepair(8)", "subsections": [] } }, "summary": "xfsrepair - repair an XFS filesystem", "flags": [ { "flag": "-f", "long": null, "arg": null, "description": "vice (see the mkfs.xfs -d file option). This might happen if an image copy of a filesystem has been copied or written into an ordinary file. This option implies that any external log or realtime section is also in an ordinary file." }, { "flag": "-L", "long": null, "arg": null, "description": "metadata changes). When using this option the filesystem will likely appear to be corrupt, and can cause the loss of user files and/or data. See the DIRTY LOGS section for more information." }, { "flag": "-l", "long": null, "arg": null, "description": "Specifies the device special file where the filesystem's external log resides. Only for those filesystems which use an external log. See the mkfs.xfs -l option, and re‐ fer to xfs(5) for a detailed description of the XFS log." }, { "flag": "-r", "long": null, "arg": null, "description": "Specifies the device special file where the filesystem's realtime section resides. Only for those filesystems which use a realtime section. See the mkfs.xfs -r option, and refer to xfs(5) for a detailed description of the XFS realtime section." }, { "flag": "-n", "long": null, "arg": null, "description": "only scan the filesystem and indicate what repairs would have been made. This option cannot be used together with -e." }, { "flag": "-P", "long": null, "arg": null, "description": "pair gets stuck and stops proceeding. Interrupting a stuck xfsrepair is safe." }, { "flag": "-m", "long": null, "arg": null, "description": "Specifies the approximate maximum amount of memory, in megabytes, to use for xfsre‐ pair. xfsrepair has its own internal block cache which will scale out up to the lesser of the process's virtual address limit or about 75% of the system's physical RAM. This option overrides these limits. NOTE: These memory limits are only approximate and may use more than the specified limit." }, { "flag": "-c", "long": null, "arg": null, "description": "Change filesystem parameters. Refer to xfsadmin(8) for information on changing filesystem parameters." }, { "flag": "-o", "long": null, "arg": null, "description": "Override what the program might conclude about the filesystem if left to its own de‐ vices. The suboptions supported are: bhash=bhashsize overrides the default buffer cache hash size. The total number of buffer cache entries are limited to 8 times this amount. The default size is set to use up the remainder of 75% of the system's physical RAM size. agstride=agsperconcatunit This creates additional processing threads to parallel process AGs that span multiple concat units. This can significantly reduce repair times on concat based filesystems. forcegeometry Check the filesystem even if geometry information could not be validated. Geometry information can not be validated if only a single allocation group exists and thus we do not have a backup superblock available, or if there are two allocation groups and the two superblocks do not agree on the filesystem geometry. Only use this option if you validated the geometry yourself and know what you are doing. If In doubt run in no modify mode first. noquota Don't validate quota counters at all. Quotacheck will be run during the next mount to recalculate all values." }, { "flag": "-t", "long": null, "arg": null, "description": "Modify reporting interval, specified in seconds. During long runs xfsrepair outputs its progress every 15 minutes. Reporting is only activated when agstride is enabled." }, { "flag": "-v", "long": null, "arg": null, "description": "" }, { "flag": "-d", "long": null, "arg": null, "description": "This is typically done on a root filesystem from single user mode, immediately fol‐ lowed by a reboot." }, { "flag": "-e", "long": null, "arg": null, "description": "0. This option cannot be used together with -n." }, { "flag": "-V", "long": null, "arg": null, "description": "" } ], "examples": [], "see_also": [ { "name": "dd", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/dd/1/json" }, { "name": "mkfs.xfs", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/mkfs.xfs/8/json" }, { "name": "umount", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/umount/8/json" }, { "name": "xfsadmin", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/xfsadmin/8/json" }, { "name": "xfsmetadump", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/xfsmetadump/8/json" }, { "name": "xfs", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/xfs/5/json" }, { "name": "xfsrepair", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/xfsrepair/8/json" } ] }