A bit of context:
(you can skip to issue ↓)
One of my APFS-formatted external HDDs suddenly became read-only, throwing this error when I plugged it in: macOS can't repair the disk.
I could still open the files on the disk, but could not save any changes to them.
Last year was a disaster for me, my old Late 2013 MacBook Pro broke twice (second time for good) and my backup external HDD died. I lost all my 2007-2018 work archive ), so needless to say the error title "macOS can't repair the disk" made me stop breathing for a second, until I read the details and realized my files aren't lost.
 Yes, I did pay for data recovery services, but only ~7-8% of my files were recovered, all from personal archive. Yes, I was stupid enough not to have cloud backup.
Disk full error and file size discrepancy
Safe mode boot and usual similar recommendations didn't help, so I gave up trying to find a cause for the sudden read-only mode and started copying my files to another external HDD which was formatted exFAT.
I noticed that copying took an incredible amount of time, and it showed in queue more files than there actually were, but shrugged and left it to run for hours. A nasty surprise followed: not only the copying wasn't even half done in all this time, but the destination disk showed as full.
That was a big wtf moment, considering that I was trying to copy about 590GB on a HDD with 3.7TB of available space. The plot thickened when I saw that the difference between file size and file size on disk for the copied files was so huge, that a 293GB folder had size on disk 2.68TB (!) It explained the "disk full" error, but posed the question how the heck is that possible.
It took me some time to find out what was going on. Actually a combo of two things lead to this:
- APFS file system created a dot file (as ._name ) for every file and directory that was copied on a non-APFS device. So practically the number of files doubled. Each ._ file was 4KB.
- My exFAT HDD had allocation unit size 1MB. When I formatted it I didn't know that exFAT has a much larger default allocation unit size than NTFS for example, and I left the default.
Due to the allocation unit size, every 4KB ._ file that the APFS file system created had a size on disk of 1MB, resulting in that huge discrepancy between the size and the size on disk of the same file.
A 1MB allocation unit size is great if all your files have sizes bigger than that, but it results in this kind of disaster if you have many small files.
APFS and the recommended Mac-exclusive format for external hard disks
APFS is apparently not recommended for HDDs. It's a proprietary format developed by Apple, but since MacBooks have used only SSDs for years now, it's a format optimized for flash storage.
If you want to format your external HDD in a Mac-exclusive format, the best choice is HFS+ (displayed as Mac OS Extended (Journaled) in the Disk Utility format options).
Make sure to select GUID partition map, not the Apple partition map. Apple partition map is a legacy option for the very old pre-Intel PowerPC Macs.
If you use your hard drive on Windows PC as well as on macOS, go with exFAT. It's the only format that will work cross-OS on Mac, Windows, Linux, and even iPadOS. But do choose carefully your allocation unit size, based on the size of individual files you will store on it.
Unfortunately, once it gets to read-only mode, the hard disk cannot be repaired. As the error text says, it needs to be reformatted, and that means that you need to backup your data on another device before you proceed.
The only way to avoid the ._ files creation that leads to the huge size differences, is to backup on another APFS device. My MacBook Pro's SSD is only 512GB (insufficient in this case for copying the files), so I ended up buying an external SSD, format it APFS and copy all my files without issues. Then formatted the broken HDD as HFS+ using Disk Utility as described above.