Like any file, a disk image can become corrupt or damaged, and like any mountable disk its file systems can also become corrupt or damaged. Although those should be very infrequent, their results can disastrous, and render the contents of that disk image inaccessible. This article suggests some solutions you can try.

In theory, if the problem is in the image’s file systems, you should be able to mount its volumes and run First Aid in Disk Utility to check and repair them. In practice that seldom works out, as macOS usually refuses to mount the image. Unless you have ready access to a recent backup, all you can do then is resort to Terminal’s command line to attempt a recovery.

Gaining access to the contents of a disk image requires two steps to complete: first the image must be attached as a device, then after probing of the file systems it contains, those can be mounted.

Read-only and compressed disk images have a checksum stored, and this is normally verified against the image file data first. If that proves invalid, then macOS will refuse to go any further.

In the past, records of checksum verifications have been stored in extended attributes such as com.apple.diskimages.recentcksum, and sometimes deleting those, or a record of the file systems being checked using fsck in com.apple.diskimages.fsck, can allow the disk image to mount. More recently those appear to have fallen into disuse.

Next you should try to attach the disk image without verification or mounting. This is best done using a command such as
hdiutil attach -nomount -noverify diskImagePath
where diskImagePath is the full path to the disk image file, such as /Users/hoakley/VMs/myImage.dmg

If this succeeds, you’ll be rewarded with a list of the resulting devices, such as
/dev/disk4 GUID_partition_scheme
/dev/disk4s1 EFI
/dev/disk4s2 Apple_APFS
/dev/disk5 EF57347C-0000-11AA-AA11-0030654
/dev/disk5s1 41504653-0000-11AA-AA11-0030654

The first is the disk device disk4, and is followed by its two standard partitions disk4s1 and disk4s2. The latter is its APFS container disk5 with its single APFS volume disk5s1. You can now check and repair the last two of those, such as
fsck_apfs -y /dev/disk5s1
which should return a blow-by-blow account of the results. If the file system is HFS+ you may also be able to use third-party repair tools such as DiskWarrior.

When you’ve completed the required repairs, detach the disk image with a command like
hdiutil detach /dev/disk4

If that fails to make the disk image mountable, some have claimed success by converting the disk image to a different format, using a command like
hdiutil convert diskImagePath -format Uxxx -o outImagePath
where diskImagePath is the original disk image, outImagePath is the new image to be created, and Uxxx is the name of a disk image type, as listed in the Appendix.

If none of these gives access to the contents you require, then it’s almost certain that the only way ahead is to find the latest backup of that disk image, and use a copy of that.

Appendix: Supported disk image formats

• UDRW – UDIF read/write, sparse file from macOS 12
• UDRO – UDIF read-only
• UDCO – UDIF ADC-compressed
• UDZO – UDIF zlib-compressed
• ULFO – UDIF lzfse-compressed (OS X 10.11)
• ULMO – UDIF lzma-compressed (macOS 10.15)
• UDTO – DVD/CD-R master for export
• UDSP – sparse image, grows with content
• UDSB – sparse bundle, grows with content, bundle-backed, Mac OS X 10.5
• UFBI – UDIF entire image with MD5 checksum.
• ASIF – sparse image, grows with content, macOS 15.

This article explains how to deal with warnings and errors reported either when you run Disk Utility’s First Aid, or by the command tools fsck or fsck_apfs, on an APFS volume or container.

Keep a record

Even if the item is repaired successfully, it’s essential to keep a record of what happened. In Disk Utility, expand the First Aid window so you can see the full output of fsck_apfs, select its whole contents, copy and paste them into a text document, and save that. Do the same with the output in Terminal if that’s what you used.

You may also find two text log files of potential use: /var/log/fsck_apfs.log and /var/log/fsck_apfs_error.log, both accessible in Console or a text editor. Although errors may also be written to the Unified log, you’ll probably want to avoid going there.

Was this on the Data volume?

First Aid in Disk Utility will check and attempt to repair the current Data volume when running in normal user mode, by effectively freezing the Mac. However, that’s not as reliable as running the same procedure when your Mac is in Recovery mode. If you see warnings or errors reported from the current Data volume in normal user mode, before going any further start your Mac up in Recovery and repeat the checks in Disk Utility (or fsck_apfs) there, to confirm they are real, and give your Mac the best chance of making a successful repair.

This can also sometimes help when checking backup volumes, and any that have proved difficult to check because the volume can’t be unmounted in normal user mode.

Are these just warnings?

Read carefully through your copy of the output of fsck_apfs and check whether the comments there are warnings, or contain specific errors. Warnings aren’t uncommon, and are often of little consequence even when you can understand them. Among the commonest is
Resource Fork xattr is missing for compressed file
As there’s nothing you could or should do about that, keep the record and don’t worry about it.

You’ll occasionally see a report that “deferred repairs” were completed. These appear to be minor fixes that APFS keeps for a convenient moment. Provided they are fixed without further error, you should be able to ignore them safely.

If a line explicitly reports an error, and fsck_apfs was unable to repair it, then it’s something you should take more seriously, and try to pin down the site of the problem.

Identify the item

fsck_apfs identifies items with their inode number, an integer that can be very large. To make any sense of that, you need the volume number as well, and a means of converting the two into a path. My free utility Mints can do that in its inode Resolver window, from the Window/Data/Inode menu command, or you can do it yourself in Terminal with a command like
GetFileInfo /.vol/[volnumber]/[inode]
where volnumber is the volume number, and inode is the number given in the error or warning. This is explained in detail here.

Now that you know which file or folder resulted in the error or warning, you need to decide whether you can do anything about it. This is most important when you keep seeing similar errors, so you can prevent them from happening in the first place.

Is the item in a snapshot?

Checking snapshot 2 of 23 (com.apple.TimeMachine.2023-08-27-072736.local)
warning: inode (id 113812826): Resource Fork xattr is missing for compressed file

Snapshots are a special case, as they’re intended to be read-only, so are most unlikely to be repairable. If this is a snapshot on a volume that is backed up by Time Machine or another utility, then the only way you’ll fix this is by deleting that snapshot. Don’t do that, though, if the snapshot is on the volume storing your backups, as you’d be deleting one of those backups.

If this problem recurs in other snapshots, then it most probably reflects a problem in the file in the snapshot. Is it perhaps a large virtual machine (VM) or something similar? Keep your VMs on a separate volume which you exclude from backups, because of the many problems they can cause. The best way to back up a VM is when it’s shut down, as a simple copy to a separate backup storage volume. You can do the same with any other file that seems to be the cause of repeated problems in snapshots: move it to a separate volume that’s in Time Machine’s list of excluded items, and make arrangements for that volume to be backed up separately when the files aren’t in use.

Is the item in a Spotlight index?

Several of those who report repeated warnings or errors in APFS trace them to part of the Spotlight indexes on that volume, which are stored at the top level of all indexed volumes, in the hidden folder .Spotlight-V100. If that’s the case, your next move is to force those indexes to be rebuilt, in the hope that fixes the problem.

To do that, open Spotlight settings, and click the Search Privacy button at the foot of its window. Use the + tool to add the volume on which the problems have been occurring, then close those settings. Leave your Mac for a minute or so, open those settings again, select the volume you just added to the list, and use the – tool to remove it. In the next ten minutes or so, check Activity Monitor’s CPU window, where you should see high levels of activity from indexing processes such as mds and mds_stores, that confirm those indexes are being rebuilt.

Is the item in another special folder?

There are other hidden folders with special roles that appear on volumes and could be the source of APFS errors. These include .DocumentRevisions-V100, containing the document version database. If the problem file is inside that, there isn’t much you can do about it. It may be possible to delete the whole folder, but that will destroy all saved versions of documents on that volume.

It’s just a regular file

If the volfs path resolves to a regular file, then maybe deleting that file will stop the problem from recurring. Don’t expect a backup copy of that file to be any different, though, as any problem with that file could easily recur. Getting to the bottom of a recurrent file system error might require the knowledge and skills of an Apple engineer. Consider reporting this using Feedback, as it should then help iron out any remaining bugs in APFS.

Is your Mac running anything that might break files?

As a final thought, you should consider whether any third-party software might be the root cause of the problem. Normally, such products should work at a higher level that isolates them from the file system itself, but there are some surprising exceptions. If you can identify a cause, please inform the developers of that software so that it can be fixed.

One potentially dangerous practice occurs when an older version of APFS changes a newer file system. APFS back in High Sierra and Mojave knew nothing of boot volume groups, firmlinks, or many of the features of more modern versions of APFS. If you really must run different versions of macOS on the same Mac, or shared external storage, avoid such version conflicts, and never run an older version of Disk Utility or fsck_apfs on a newer APFS container or volume.

Look in Apple’s support note explaining Safe mode, and you’ll see a list of three things that mode is claimed to do:

• “Prevents certain software from loading as your Mac starts up. This includes login items and extensions that aren’t required by macOS, and fonts that weren’t installed by macOS.”
• “Performs a basic check of your startup disk, similar to the more comprehensive check performed by the First Aid feature of Disk Utility.”
• “Clears some system caches, including font caches and the kernel cache, which are automatically created again as needed. This can temporarily make more storage space available on your startup disk.”

That note is well-maintained, and its US version was last updated on 5 December last year. This article examines what “basic check of your startup disk” is performed, how “similar” it is to the First Aid feature in Disk Utility, and whether it differs from checks performed during startup in normal mode. All testing has been performed in macOS 26.3 Tahoe on Apple silicon Macs.

Reporting

Disk checks made in Safe mode aren’t reported to the user in the GUI. There’s no notification that they have been completed, neither is there any record made in System Information. They are, though, reported in three more obscure places most folk won’t try accessing:

• /var/log/fsck_apfs.log, accessible in Console or a text editor,
• /var/log/fsck_apfs_error.log, accessible in Console or a text editor,
• the Unified log, accessible using a log browser such as LogUI.

A typical entry in the first of those, for the Data volume, reads
/dev/rdisk3s5: fsck_apfs started at Mon Mar 2 06:46:45 2026
/dev/rdisk3s5: error: container /dev/rdisk3 is mounted with write access; please re-run with -l.
/dev/rdisk3s5: fsck_apfs completed at Mon Mar 2 06:46:45 2026

Seven of the volumes checked during startup report that same error, and the only two in the boot volume group that report completion of the check are the System volume, unmounted during normal running, and the Signed System Volume, which has its own error-checking and is a snapshot in any case. Those that do complete and provide further information uniformly report
/dev/rdisk7s3: ** QUICKCHECK ONLY; FILESYSTEM CLEAN

fsck_apfs_error.log contributes no useful information, as many of its entries are uninformative, for example
dev= uuid=00000000-0000-0000-0000-000000000000 vers=2632.80.1.0.1 default_ans=n result=0 fp=0 fl=-1 repairs=0 time=0 iter=1
fsck_apfs completed at Mon Mar 2 06:46:45 2026
which completely fails to identify the volume being reported.

Corresponding entries in the Unified log for the Data volume are similar to those in fsck_apfs.log:
06:46:45.153989 com.apple.DiskArbitration.diskarbitrationd probed disk, id = /dev/disk3s5, with apfs, ongoing.
06:46:45.175308 com.apple.DiskArbitration.diskarbitrationd fsck status 65 /dev/rdisk3s5
06:46:45.182032 com.apple.DiskArbitration.diskarbitrationd probed disk, id = /dev/disk3s5, with apfs, success.

Checks performed

It’s clear from those reports that fsck_apfs is performing a ‘quick check’ of each volume after it has been mounted ready for use. According to man fsck_apfs, that “causes fsck_apfs to quickly check whether the device is `clean’. If device is an APFS volume, fsck_apfs will quickly check the APFS container and the specified APFS volume.” A status code of 65 is well-known from First Aid in Disk Utility as indicating that the volume being checked was mounted for writing at the time, so no check has been performed, as that would require the volume to be unmounted first.

First Aid checks

Normally, running First Aid in Disk Utility on a volume causes that volume to be unmounted, and a full fsck_apfs to be performed, in which any errors found will be repaired if possible. In addition to checking that volume, any snapshots of it will also be checked, although they cannot normally be repaired. Checking snapshots is time consuming, and when using the command tool fsck_apfs can be skipped using the -S option, although that’s not available in Disk Utility, which automatically includes snapshot checks.

Normal startup

Exactly the same checks as those made in Safe mode are also performed at the same point when starting up in normal user mode, but not when starting up in Recovery mode. Reporting in fsck_apfs.log and the Unified log is identical, with the same volumes returning status 65 each time.

In this respect, Safe mode is no different to normal user mode.

History

Prior to the introduction of macOS Catalina in 2019, starting up in Safe mode resulted in a full scan of all volumes and snapshots using fsck_apfs in normal mode. As that could take an hour or more, and delayed startup for the whole of that period, checks changed in Catalina, since when they have only used quick checks. Despite that, Apple has continued to claim that one of Safe mode’s features is checking disks similarly to First Aid in Disk Utility.

Q&A

Does Safe mode perform “a basic check of your startup disk”?
Although quick checks are attempted during startup in Safe mode, because of the circumstances, they can’t be run on the Data volume, but they should complete on external volumes.

Is that check “similar to the more comprehensive check performed by the First Aid feature of Disk Utility”?
No. When it is able to complete, all it does is verify the file system is ‘clean’ and not already in need of repair. Checks in First Aid are more extensive, include any snapshots, and include any repairs found to be necessary.

Do the disk checks performed in Safe mode differ from those that occur during normal startup?
No. Safe mode doesn’t add any disk checks beyond those that already occur during normal startup.

Recommendations

If you want to check any of your Mac’s volumes or disks, don’t try using Safe mode. Instead, use First Aid in Disk Utility (or fsck_apfs). If you want to check one of the volumes in the current boot volume group, prefer doing so in Recovery mode.