APFS Object Map Recovery
I spent a day figuring out how to look into a corrupt encrypted APFS partition. Here’s the notes.
If you only care about the answer, jump to the last section.
macOS hard panicked on me me with our favorite graphics driver common interface corruption com.apple.iokit.IOAcceleratorFamily2 which happened after seven “gpuRestart” logs were generated back-to-back.
After the reboot and a login, the system crashed again while applications were starting up. Not good.
After the next reboot, the system started okay, but since applications crashed while starting, they lost all of their historical state. Chrome lost all open windows and tabs. Terminal lost all open windows and tabs. Drat.
So, off to backups to restore Chrome windows/tabs and Terminal windows/tabs from old saved states.
Now with windows restored to how they looked two weeks ago, let’s see what else went wrong during a double crashing reboot.
I launched VLC to watch something from my media drive and… my 2 TB USB drive wasn’t mounted.
No problem, just hop into Disk Utility and mount it.
Except—this looks odd.
Odd and wrong. Uninitialized? I’m not uninitialized, you’re uninitialized! Odd and wrong and ohcrapwhereismydrive.
It’s not the end of the world (the drive is just downloaded media), but I worked hard for these files and I’d rather not lose them.
First Aid on
AppleAPFSMedia (which is
What if we try
First Aid on
APFS Physical Store disk2s2 instead?
Running First Aid on “” (disk2s2) Repairing storage system Performing fsck_apfs -y -x /dev/disk2s2 Checking the container superblock. Checking the space manager. Checking the space manager free queue trees. Checking the object map. Checking volume. Checking the APFS volume superblock. The volume Blue Diamond was formatted by diskmanagementd (945.230.6) and last modified by apfs_kext (945.275.7). Checking the object map. error: om: btn: invalid o_oid (0x233b75) Object map is invalid. The volume /dev/disk2s2 could not be verified completely. Storage system check exit code is 8. Storage system verify or repair failed. Operation failed…
fsck_apfs can see the volume name now, our overall feeling is still no no no no no no
diskutil apfs list think?
APFS Containers (2 found) | +-- <ignoring system drive here> | +-- Container ERROR -69808 ====================== APFS Container Reference: disk3 Size (Capacity Ceiling): ERROR -69620 Capacity In Use By Volumes: ERROR -69620 Capacity Not Allocated: ERROR -69620 | +-< Physical Store disk2s2 | ----------------------------------------------------------- | APFS Physical Store Disk: disk2s2 | Size: 2000189177856 B (2.0 TB) | +-> No Volumes
things are looking pretty awful
Apparently, in 2019, Apple has a file system corruptible by crash reboots and also can’t be repaired by their own tools. Everything is fine.
A data recovery tool appears
Searching online for recovering from APFS
Object map is invalid errors brings us to a site called “iboysoft” which is a utility with pretty good marketing SEO for file system problems.
Of course each fix of theirs is “our software fixes it! Pay us $99 to recover your data!”
My only only option now is to download a utility called “iboysoft” from an anonymous Chinese company with promises it can recover unreadable APFS partitions.
So we download.
And we run.
And… it shows me all files on the drive! Thanks, “iboysoft,” and shame on you, Apple.
Of course, it only shows you file names and file previews in trial mode. Actually restoring files costs $99.
Before I throw away $99 to recover within-arms-reach files, I do some more searching… either the people behind this utility reverse engineered APFS from half complete docs Apple provides or they are using other public code underneath (spoiler: I never found out if the utility was all custom code or reusing open source code just packaged in a UI1).
but what about GitHub?
What about APFS recovery tools lurking around on GitHub? If a random anonymous online app can fix my drive, what about public utilities?
A read-only apfs info util
First, we found apfs-tools (via Apple SE: Accessing unmountable APFS Volume on a disk image) currently being maintained/created/updated with a hand written APFS parser — but, it won’t open my encrypted APFS volume, and Apple’s own tools won’t provide a decrypted volume view because
diskutil apfs unlockVolume doesn’t recognize the broken APFS volume or drive at all.
A swing and a miss.
A full apfs library
Next up, we find a thing called libfsapfs currently being maintained/created/updated with a different hand written APFS parser, and this one includes support for reading encrypted volumes!
Also it looks like
libfsapfs includes some binary utilities so we won’t have to interface with the library directly for quick tests.
Let’s compile it from a release:
libfsapfs includes binaries, but we don’t know where they are or where they got built.
Those look useful!
./fsapfsinfo gives us help of:
fsapfsinfo 20191104 Missing source file or device. Use fsapfsinfo to determine information about an Apple File System (APFS). Usage: fsapfsinfo [ -B bodyfile ] [ -E identifier ] [ -f file_system_index ] [ -F path ] [ -o offset ] [ -p password ] [ -r password ] [ -hHvV ] source source: the source file or device -B: output file system information as a bodyfile -E: show information about a specific file system entry or "all" -f: show information about a specific file system or "all" -F: show information about a specific file entry path -h: shows this help -H: shows the file system hierarchy -o: specify the volume offset -p: specify the password -r: specify the recovery password -v: verbose output to stderr -V: print version
oh look, it has a simple
-p option to enter the password of an encrypted volume!
and we can use
-H to print a list of everything it can see on the filesystem, which, when we run it, ends up being the same list of files discovered by the “iboysoft” recovery utility from before:
It looks like we may be able to avoid paying $99 to recover files from our corrupted APFS volume after all.
Recovering APFS Volume using
The other command is
fsapfsmount which seems like our goal. All we really need is to mount our system-unreadable volume so we can copy the files somewhere safe.
Let’s try to mount. The mount command follows normal syntax with the mount point being the last argument.
Not available? File system not available? Oh,
osxfuse not available. We probably didn’t have mac fuse installed. Let’s fix with:
But now we also have to rebuild
libfsapfs so it can pick up fuse:
Now let’s try the mount again! (you will get a macOS system extension error where you need to manually approve the fuse extension in System Preferences, so do the approval dance then continue from here…)
iconpath and why do we care?
Back to google… (in reality we tried to mount another couple times, rebooted, then asked google)
We get an unrelated project issue declaring mac fuse requires a path to an icon library to show disks or else it won’t mount anything. sure, why not. remember: defaults matter. Don’t make users search for weird things when the default could just work hardcoded (obviously you need an icon repository to mount your disk, right?).
Back we go to mounting, but we may need to clean up the previous failed mount first.
The previous failed mount did (oddly) use the mount point even though it didn’t mount anything. Let’s free the directory.
Now try again (the same command as before, but now with
And it worked! At least it worked for me.
ls got and… there are all our files! We didn’t have to pay a weird company named “iboysoft” $99 to recover files Apple corrupted away from us. We just had to pay whatever our time was worth for the 5 hours it took to track down all of these solutions.
rsync -av --progress --partial got/* /Volumes/NewDrive/ for about 20 hours. After a mostly complete transfer (you may have some data errors, but rsync will skip over them to continue), you can reformat your corrupt drive as not APFS because APFS shouldn’t be used on external spinning rust drives at all, as we’ve seen through this entire mess. It’s okay though, we didn’t have anything else better to do today than babysit poorly written OS-provided system utilities and sleuth the Internet neck deep in error reports for half a dozen manual workarounds.
but after this article, you could package open source code in a cheap UI and charge $50 for APFS corruption recovery instead of everybody else’s price of $99. It would be a good deal.↩