Fixing “app is damaged”

macOS uses one dialog for two different failures. One is a quarantine flag on a file you just downloaded. The other is a file that really does not match its signature. They look the same. They are not the same, and I do not treat them as the same on a lab image.

Why the dialog appears

Gatekeeper checks a signature and a notarisation ticket, and it also checks a quarantine attribute that browsers and Mail set on downloads. A brand-new copy of an app you trust can still trip the dialog, because the attribute says "this came from the internet" and the check wants a moment you did not give it.

The wording is worse than the mechanism. "Damaged" sounds like a bad disk. Often the binary is fine and the attribute is the whole story. Sometimes the binary is not fine. The dialog will not tell you which. You have to look.

The quarantine attribute

The attribute is com.apple.quarantine. You can see it without changing anything:

$ xattr -l /Applications/Example.app

If that line is present, and you obtained the app from the place you meant to, clearing the attribute is the ordinary next step. If the line is absent and the dialog remains, stop. You are not looking at a quarantine problem.

Clearing it, when you have decided the file is the one you downloaded:

$ xattr -d com.apple.quarantine /Applications/Example.app

Then open the app once from the admin account and watch what Gatekeeper says the second time. I do this on a machine I can reimage, not on the only copy of someone's coursework.

A careful open

Right-click, Open, is the other path Apple still documents. It is a prompt, not a bypass of a bad signature. If the second dialog names a developer you recognise, and the file size matches the row on this site, I continue. If the developer line is blank or absurd, I do not.

I also check the version against the row before I copy the app onto an image. A dialog is not a reason to grab a different build from a different folder because it "opens". The build that opens might be the wrong year.

When the message is telling the truth

A truncated download, a disk image that did not finish copying to the imaging Mac, or a file that was edited after it was signed: those are real damage. Clearing quarantine will not repair them, and it should not. If codesign --verify --deep --strict complains, I delete that copy and download again. I do not keep a half-signed app "because the lesson starts in ten minutes".

I also do not turn Gatekeeper off for the machine. A lab image with the checks disabled is a favour to the next person who plugs in a USB stick. The ten minutes are not worth the term.

On a lab image

If one app on one Mac shows the dialog, I treat it as that copy. If the same dialog appears on a row of Macs after an image, the attribute was baked into the image, or the file in the image is the bad one. I fix the image, then reimage. I do not walk the room clearing attributes by hand and call it done.

Write down which build you put on the image. The row on this site is there so that note has a version and a size, not so that the dialog can be ignored.