MacOS – fsck_apfs not working from terminal in single user mode

apfscatalinafsckmacos

I am trying to fix errors on my MacIntosh HD Data volume.

I have tried to fix using Disk Utility from normal mode and from recovery mode. Same problem. DI hangs at a certain point and that's it.

I boot into single user mode.

Using df -h I see that the MacIntosh HD Data volume is /dev/disk2s1.

I try to type:

fsck_apfs -y /dev/disk2s1

and I get this:

error: device is unreadable because you are in single user mode.

I try the same command from normal boot and I get

error: container /dev/rdisk1 is mounted with write access.

I have done this thousands of times before, from single user mode. This is some Catalina crap.

How do I do that now on Catalina?

Best Answer

Correction

Apple's official word is that the traditional single-user mode which one enters by booting whilst holding ⌘S is deprecated on macOS Mojave (10.14) and later. This is due to the presence of the Apple T2 security chip in Macs which initially went to market with Mojave or later.

From Mac startup key combinations:

And from the small print on the linked "single-user mode" page, Start up your Mac in single-user mode or verbose mode:

These steps replace the Command-S method, which doesn't work with the recommended settings on current Mac computers.

The linked page "current Mac computers" refers to those which have a T2 chip.

Despite the claim that the traditional single-user mode is outright disabled on Mojave and later, you can still boot into it using ⌘S on devices which don't have a T2 chip, even if you attempt to do so on a system running Mojave or later. However, this single-user mode will require access to the data and VM volumes of the APFS container that contains the OS, and you will find that you are unable to unmount these volumes in order to run fsck_apfs -y on that container. This is because umount will refuse to unmount the volumes due to them being actively used, and you cannot forcibly unmount them using diskutil since the DiskManagement framework required by diskutil is not loaded/present in this mode — and even if this were possible in some other way, it is unadvisable to forcibly unmount elements of a filesystem that you are trying to repair!

Having said that, macOS still technically has a single-user mode in Mojave and later: the Terminal in macOS Recovery. After actually trying to use fsck_apfs -y in this environment, it turns out that it is possible, but you will first need to unmount any mounted APFS volumes belonging to the APFS container that contains the OS; macOS Recovery will automatically mount the data and VM volumes by default. Because macOS Recovery isn't as stripped down as the traditional single-user mode, you can do this simply with e.g. diskutil unmountDisk disk2. You can use mount and diskutil apfs list to determine the device nodes.

Original answer

This isn't a Catalina thing, but an APFS thing. You cannot perform reparatory actions on an APFS container (or any of its volumes, since this requires acting on the container) when that container is mounted. If any volume in that container is mounted, then the container itself is necessarily also mounted.

As such, you cannot use fsck_apfs -y on the APFS partition that you have booted from, whether that's in a regular environment, in single-user mode, in recovery mode, or however else. You can still run fsck_apfs -nl when booted normally to inspect the APFS partition for errors, but this will not repair any such errors.

To run fsck_apfs -y on your Catalina APFS partition, you must access could also try accessing the disk another way, such as:

  • booting into Catalina Internet Recovery (which also requires you to unmount the automatically mounted volumes).
  • booting from a Catalina USB installer.
  • booting your Mac in Target Disk Mode and connecting it to a secondary Mac running Catalina, then running fsck_apfs from the secondary Mac on the affected disk.
  • physically removing the disk from your Mac and connecting it to a secondary Mac running Catalina, then running fsck_apfs from the secondary Mac on the affected disk.

Since new, significant APFS features were introduced in Catalina ("volume groups" in particular), avoid using any fsck_apfs belonging to an older macOS version, particularly if you are trying to repair incorrectly allocated disk space. fsck_apfs(8) states for the -o option:

-o — Repair overallocations; please do not run an older fsck_apfs on newer systems with this option.

Related Question