TheCSGuide

Mac software, under the hood

Fixing “app is damaged”

macOS uses one dialog for two different failures. One of them is a quarantine flag. The other is a signature that actually doesn't check out. They look the same. They are not the same, and the fix for the first one is a bad idea to apply to the second.

Why macOS says the app is damaged

Gatekeeper runs when you open something that arrived from the internet. A downloaded dmg gets a quarantine attribute, com.apple.quarantine, stuck in the file's extended attributes. On first open, macOS checks the code signature and, for anything that wants a quiet life, the notarization ticket. If that check fails — or if the flag is there and the ticket lookup hiccups — you get the damaged-app sheet. The wording is dramatic on purpose. It is not a disk error.

The quarantine attribute

You can see the flag without changing it:

$ xattr -l ~/Downloads/Compresto.dmg
com.apple.quarantine: 0083;00000000;Safari;...

The attribute rides along when you copy the app out of the dmg, which is why dragging to Applications doesn't clear it. A lot of "just move it" advice on forums is wrong about that. The flag is metadata, not a bit inside the Mach-O.

Clearing it is a one-liner, and I want you to know what it does before you run it. xattr -d com.apple.quarantine on the .app tells Gatekeeper to stop treating this copy as a fresh download. It does not repair a bad signature. It does not make a modified binary safe. It only removes the "this just came from a browser" mark.

What notarization actually checks

Notarization is Apple's record that a specific signed build was submitted and scanned. The ticket is stapled to the app or fetched online the first time you open it. A stapler failure — no network, a clock that's hours off, a ticket that was never stapled — can look exactly like a broken app. The binary may be fine. spctl -a -vv on the path will say accepted and name the developer if the signature itself is good.

$ spctl -a -vv /Applications/Compresto.app
/Applications/Compresto.app: accepted
source=Notarized Developer ID

If spctl says rejected, stop. Don't clear quarantine to push past a real rejection. That dialog is finally telling the truth: the bytes don't match a signature you should trust.

A careful way to open the binary

  1. Check the architecture with lipo -info so you know you didn't grab the wrong slice.
  2. Run spctl as above. Accepted means the signature is the developer's.
  3. If it is accepted and the only complaint is the damaged sheet, remove the quarantine attribute from the .app bundle, not from a random file inside it.
  4. Open once from the Finder with the control-click Open path if System Settings still wants a human to confirm.
  5. If spctl rejects the bundle, delete it and download the build again. A half-written dmg is a more common cause than a conspiracy.

When the message is telling the truth

A damaged dialog is correct when the hash doesn't match, when someone patched the executable, or when the download stopped early and the code signature trailer is missing. I would rather you re-download than train yourself to dismiss the sheet. The catalog lists a size on the card for this reason. If the dmg on disk is nowhere near that size, it is not the build I wrote about.

Nothing on this page is a bypass for a binary you didn't mean to run. It's a way to tell a sticky attribute from a bad file, which is a distinction the dialog refuses to make.

Back to top