Fixing “app is damaged” on macOS

The dialog sounds like the file is broken. A lot of the time it is not broken. Gatekeeper is saying it will not vouch for the download, and it uses a harsher sentence than the situation deserves. Read this before you start deleting protections you do not understand.

Why the dialog says damaged

macOS keeps a short opinion about every file you got from a browser, from Mail, or from a chat app. The opinion is not “this file is corrupt.” The opinion is “this file came from somewhere else, and I have not been introduced.” For a notarized app from a developer Apple already knows, the introduction is quiet and you never see a dialog. For a small utility, you often do.

The wording changed over the years. Sometimes it says the app cannot be opened because the developer cannot be verified. Sometimes it says the app is damaged and should be moved to the Trash. The second sentence is the one that panics people, and it is often the same underlying refusal wearing a worse coat. A checksum can still be intact. The system is objecting to the origin, not to a truncated zip.

I hit this a few times a year, usually on a build I just listed, usually on a Mac that has been told to be strict. It is annoying. It is also the thing standing between a random disk image and your Applications folder. I do not turn it off globally. I deal with the one app I meant to open.

The quarantine flag

When Safari, Chrome, or Mail saves a file, macOS attaches a quarantine attribute. You can think of it as a note on the file: downloaded, on this date, by this program. Gatekeeper reads the note the first time you open the app. If the signature and the notarization satisfy it, the note is settled and the app opens the next time without the conversation. If they do not, you get the dialog, and the note remains.

Moving the app to the Trash and downloading it again does not always help, because the new copy gets a new note. Installing it from a disk image you copied off a USB stick you trusted is a different path from a browser, and the note may never have been written. That is why the same build can open on one Mac and complain on another. The bytes match. The note does not.

You do not need a terminal for the ordinary case. I am mentioning the attribute so the dialog stops feeling like superstition. There is a flag. The system is honoring it. Clearing every flag on the machine with a command you pasted from a forum is how a cautious feature becomes a hole. Do not do that “just in case,” and do not run a script that walks your whole disk.

Opening it the ordinary way

For an app you meant to download, from a page you meant to be on, the first attempt is the one Apple documents, not a workaround.

1. Move the app to Applications if it is still sitting in the disk image. Eject the image.
2. In Finder, open Applications, and Control-click the app (or right-click).
3. Choose Open. If macOS repeats the warning, choose Open again in that dialog. This is a one-time confirmation, not a setting you have to find later.
4. If the item does not appear, open System Settings, then Privacy & Security, and scroll to the note about the app you just tried. Use Open Anyway only if the name matches the app you downloaded.

That second Open is the entire trick for a large share of these dialogs. People miss it because the first dialog offered only Done or Move to Trash, and the useful button shows up on the next try. I have watched careful people throw away a good download here. Try the Control-click once before you assume the file is garbage.

After a successful open, the conversation should be over. The next launch is a normal double-click. If macOS asks every single time, you are not looking at a quarantine note anymore. You are looking at a signature that fails, or an app that was modified after it was signed. That is the next section’s problem, not this one’s.

When you should stop

Stop if you do not recognize the download. A dialog is not a puzzle you are obliged to solve. “Damaged” is a fine reason to delete a file you did not go looking for. The catalog lists programs by name and version so you can check that the thing in your Downloads folder is the thing you clicked. If the name is off by a word, or the disk image is vastly larger than the size written on the page, do not talk Gatekeeper out of its opinion.

Stop if a stranger’s page, a comment, or a chat message handed you a command whose job is to remove quarantine from everything. A note about one app you installed is a decision. A command with a wildcard is a different decision, and it is not the one I am describing. I will not print those commands here. They are easy to find and easy to regret.

Stop if the app wants an administrator password before it has even shown a window. A utility can need a password later, for a helper you understand. A disk image that asks before you have seen the program is in a hurry. Close it.

• The name should match the page, including the version if the filename has one.
• The size should be in the neighborhood of the size on the page. An 11 MB app that arrives as 200 MB is not a bonus.
• You should be able to say, in one sentence, why you downloaded it.

If it still will not open

Download it again from the same page, once. Browsers do truncate files, and a truncated disk image really is damaged, in the ordinary sense of the word. The second copy either opens or it fails the same way. If it fails the same way, the file is probably whole and the system is still refusing the signature.

Try the previous version listed on the program’s page if you are on an older macOS than the current build expects. A mismatch there produces confident, wrong errors. The requirements tab is dull on purpose. Read it.

Then write to me if the build on this site is the one that will not open, and say which Mac and which macOS. I would rather pull a bad file than have you collect three forum fixes and apply all of them. The address is on the about page. Tell me the program name, the version, and the exact sentence in the dialog. A screenshot of the dialog helps. A screenshot of your desktop does not.

I keep the list short so that “I meant to open this” stays a sentence you can actually mean. Gatekeeper is allowed to be fussy. So am I. Between the two of us, the app either earns the Open button once, or it goes in the Trash and off the machine.