How to repair a sparsebundle image

In this tutorial I will show you how to repair a sparsebundle image. It's not difficult but it can take some time, depending of the size of your image. Also, please do note that some images are so damaged that they cannot be repaired so do not throw stones at me if you cannot fix yours. The examples below were used against a image used as TimeMachine backup. You need some command line (terminal) skills for this tutorial.

1. Make sure the image and everything inside is not locked:

PS: if you do not do this unlock, your image will not be repaired automatically and if you try to do it manually you will get Unable to open block device /dev/disk8s2: Permission denied

osx:server root# chflags -R nouchg fbmbp.sparsebundle

2. Mount the image with the following parameters:

osx:server root# hdiutil attach -nomount -noverify -noautofsck fbmbp.sparsebundle
/dev/disk8          	Apple_partition_scheme         	
/dev/disk8s1        	Apple_partition_map            	
/dev/disk8s2        	Apple_HFSX

PS: if on the above command you get hdiutil: attach failed - Resource temporary unavailable and you are 100% sure it is not currently mounted somewhere, create another similar sparse bundle image and replace the file "token" from your image with the one from the new image. To create another image, do the following (replace JHFS+ with APFS if you have macOS higher or equal with Big Sur):

osx:Backups root# hdiutil create -library SPUD -size 1m -fs JHFS+ -type SPARSEBUNDLE temp.sparsebundle
created: /Volumes/fl/Shared Items/Backups/temp.sparsebundle
osx:Backups root# cd fbmbp.sparsebundle
osx:fbmbp.sparsebundle root# mv token token.bkp
osx:fbmbp.sparsebundle root# cp ../temp.sparsebundle/token .

Now, if you fixed the token thing (only if necessary), let's move forward but before that try again the

hdiutil attach

command from the beginning of point 2. In our example, the target volume that needs to be repaired is Apple_HFSX. At this point, amazingly the system should start already the fsck in the background. This can take a while so do something else to not get bored. To follow its execution, please use the following command (ctrl+c to exit):

osx:server root# tail -f /var/log/fsck_hfs.log

My output of this command was:

/dev/rdisk8s2: fsck_hfs run at Thu Oct 31 20:58:30 2013
/dev/rdisk8s2: ** /dev/rdisk8s2 (NO WRITE)
/dev/rdisk8s2:    Executing fsck_hfs (version diskdev_cmds-491~1).
QUICKCHECK ONLY; FILESYSTEM CLEAN
** Checking extended attributes file.
** Checking multi-linked directories.
** Checking volume bitmap.
** Checking volume information.
** Repairing volume.
** Rechecking volume.
** Checking Journaled HFS Plus volume.
** Detected a case-sensitive volume.
** Checking extents overflow file.
** Checking catalog file.
** Checking multi-linked files.
** Checking catalog hierarchy.
** Checking extended attributes file.
** Checking multi-linked directories.
** Checking volume bitmap.
** Checking volume information.
** The volume Time Machine Backups was repaired successfully.

^C
osx:server root#

Now, if the final line contains: - "QUICKCHECK ONLY; FILESYSTEM CLEAN", probably only the "token" file was bad (if you had to fix it in previous step) just go to point 3 and see if you are OK with the rest and if your computer cannot mount the timemachine volume, go for step 2a; - "The volume was repaired successfully", you are good to go for the point 3; - "The Volume could not be repaired", you have to do extra steps unfortunately. Please Follow the point 2a (moved at the end, to avoid misunderstandings). - "QUICKCHECK ONLY; FILESYSTEM DIRTY", you have to do extra steps. Follow the point 2a.

3. Umount the volume:

osx:server root# hdiutil detach /dev/disk8

4. Now you need to edit the plist file within the image. To the "unix" eyes, this image is a simple directory. Please cd do it with confidence, I know what I am doing :)

osx:server root# cd fbmbp.sparsebundle/
osx:fbmbp.sparsebundle root# ls
Info.bckup  					com.apple.TimeMachine.MachineID.plist
Info.plist  					com.apple.TimeMachine.Results.plist
bands  						com.apple.TimeMachine.SnapshotHistory.plist
com.apple.TimeMachine.MachineID.bckup  		token

You will have to edit com.apple.TimeMachine.MachineID.plist and modify the VerificationState state from 2 (or 1) to 0. On rare occasions, you have to delete that entirely if Time Machine still cannot use your image even if it was repaired.

osx:fbmbp.sparsebundle root# cat com.apple.TimeMachine.MachineID.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>RecoveryBackupDeclinedDate</key>
	<date>2013-10-31T21:26:37Z</date>
	<key>VerificationDate</key>
	<date>2013-10-31T17:57:47Z</date>
	<key>VerificationExtendedSkip</key>
	<false/>
	<key>VerificationState</key>
	<integer>0</integer>
	<key>com.apple.backupd.HostUUID</key>
	<string>00000000-FE00-00D0-0000-00000000000</string>
	<key>com.apple.backupd.ModelID</key>
	<string>MacBookPro6,2</string>
</dict>
</plist>

END! Do not go to step 2a if you just did the step 4. Following is only for those who were not successful at the end of the step 2!

2a. Follow this step only if you were not successful at the end of point 2. Do further repairs with the

fsck_hfs

command:

PS: If you get "Unable to open block device /dev/disk7s2: Permission denied", you probably forgot to do step 1. Sometimes it is because hdiutil simply was not able to automatically mount the partition read/write. You will have to remount it with the option

-readwrite

.

osx:server root# fsck_hfs -drfy /dev/rdisk8s2
** /dev/rdisk8s2
	Using cacheBlockSize=32K cacheTotalBlock=4096 cacheSize=131072K.
   Executing fsck_hfs (version diskdev_cmds-491~1).
	Journal replayed successfully or journal was empty
** Checking Journaled HFS Plus volume.
** Detected a case-sensitive volume.
** Checking extents overflow file.
** Checking catalog file.
** Rebuilding catalog B-tree.
hfs_UNswap_BTNode: invalid node height (1)
** Rechecking volume.
** Checking Journaled HFS Plus volume.
** Detected a case-sensitive volume.
** Checking extents overflow file.
** Checking catalog file.
** Checking multi-linked files.
** Checking catalog hierarchy.
** Checking extended attributes file.
** Checking multi-linked directories.
	privdir_valence=55774, calc_dirlinks=133217, calc_dirinode=55774
** Checking volume bitmap.
** Checking volume information.
   Invalid volume file count
   (It should be 3396406 instead of 3396402)
   Invalid volume free block count
   (It should be 21745413 instead of 21745417)
	invalid VHB nextCatalogID 
	invalid VHB attributesFile.clumpSize 
   Volume header needs minor repair
(2, 0)
   Verify Status: VIStat = 0x8000, ABTStat = 0x0000 EBTStat = 0x0000
                  CBTStat = 0x0000 CatStat = 0x00000000
** Repairing volume.
** Rechecking volume.
** Checking Journaled HFS Plus volume.
** Detected a case-sensitive volume.
** Checking extents overflow file.
** Checking catalog file.
** Checking multi-linked files.
** Checking catalog hierarchy.
** Checking extended attributes file.
** Checking multi-linked directories.
	privdir_valence=55774, calc_dirlinks=133217, calc_dirinode=55774
** Checking volume bitmap.
** Checking volume information.
** The volume Time Machine Backups was repaired successfully.

If you still get "The Volume could not be repaired", then I am so sorry but I have no other options for you. If you are successful, follow the point 3.