Fixing “app is damaged”

macOS sometimes refuses a download with the line that the app is damaged and should be moved to the bin. I see this a few times a year on the team Macs, usually on a build I have already ticked. The message sounds final. It usually is not. This note is the order I follow before anyone starts turning security settings off.

What the message actually means

Most of the time the file arrived from a browser, and macOS has marked it as quarantined. Gatekeeper then fails the check and uses the word “damaged” even when the disk image is whole. It can also mean the download really is truncated, or that someone handed you a build I have never filed. Those are different problems. The first is a flag. The second is a bad file. The third is not going on a work Mac.

I do not treat the wording as a diagnosis. I treat it as a stop. Nobody installs a second copy “from a mirror I found” while I am still looking at the first one.

The checks I do first

1. Confirm the download finished. A 11 MB image that arrived as 4 MB is not damaged in the poetic sense. It is incomplete. Download it again from the link on the program page.
2. Compare the version with the page. If the filename says one thing and the page says another, stop.
3. If you are on the team, compare the checksum with the ticket. I do not publish checksums on the open web. The ticket is the place.
4. Eject any half-mounted image and move the failed copy out of Downloads so the next person does not launch it by habit.

The quarantine flag

If the size and the version match, the usual cause is the quarantine attribute. This is the command I use, aimed at the app after it has been copied into Applications, not at a random file a search box found:

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

Replace the path with the actual app. I do not run this against the whole disk, and I do not wrap it in a command that clears every attribute on every download. One app, one attribute, one reason. Then open the app once from the Applications folder, not from the disk image.

If the command says the attribute is not there, do not keep typing variations until something changes. That is how a cautious check becomes a mess. Tell me the exact output.

When I do not bypass it

I do not turn off Gatekeeper for the whole Mac. I do not install a tool whose only job is to strip checks from everything you download. I do not follow a forum post that starts with “paste this into Terminal” if it is longer than the one-liner above. If a client’s IT has a profile that blocks the app, the fix is a conversation with them, not a local workaround that they will reverse on Monday and blame us for.

If the build is not on this list, the damaged message is a reason to leave it off the machine, not a puzzle to solve. Unlisted software does not get a clever install.

After it opens

Once it opens, I check the version in the app menu against the page, then I quit it and look in Activity Monitor for a helper that stayed behind. If a helper is still there and the program page does not mention it, I want to know. Eject the disk image. Do not leave it on the desktop “in case”.

If it still will not open after the attribute is cleared and the checksum matches, the file is done. Download the previous version from the program page, the one I have left a link for, and tell me. Do not keep the broken copy beside the working one. Two icons with the same name is how the wrong build gets used in a client pack.

This note will not grow into a general Terminal guide. The one command is the one I am willing to put next to my name. If Apple changes the message, I will change the note after I have seen it on a machine in this office, not after I have read a headline.