"App is damaged and can't be opened": the fix for developers

When your users see "is damaged and can't be opened" on macOS, the download is almost never corrupted. Your build failed Gatekeeper's check. Here's how to find out which part failed, and how to fix it so nobody sees that message again.

A cracked wax seal on a closed envelope

"MyApp is damaged and can't be opened. You should move it to the Trash." If your users are sending you screenshots of that message, the file they downloaded is almost certainly intact. What macOS means is that the app came from the internet and its code signature is missing, broken, or not what Gatekeeper expects.

This page is for the developer of the app. If you're a user trying to open someone else's app, the page on xattr -cr explains your options.

The short version of the fix: sign every piece of code in the bundle with a Developer ID certificate and the hardened runtime, notarize the thing you actually ship, staple the ticket, and don't touch the bundle after signing. The rest of this page is how to find out which of those went wrong.

Why it works on your Mac and not on theirs

Gatekeeper only checks files that carry the quarantine flag, an extended attribute called com.apple.quarantine that browsers, mail clients and chat apps add to anything they download. An app you built locally never gets that flag, so it opens on your machine no matter how badly it's signed.

That's why this bug survives testing. To see what your users see, you have to do what they do: download the release from your website in a browser and open it, ideally on a Mac that has never had the app or your certificates on it.

Diagnose it in three commands

Run these on the app as your users receive it: download the release, unzip it or mount the disk image, and point the commands at that copy.

1. Is the signature valid?

codesign -vvv --deep --strict MyApp.app

A good build prints valid on disk and satisfies its Designated Requirement. Anything else names the problem and usually the file: code object is not signed at all, a sealed resource is missing or invalid, or invalid signature. This is the check Apple's notarization docs recommend, and --strict matches what notarization requires.

2. Would Gatekeeper let it run?

spctl -vvv --assess --type exec MyApp.app

You want accepted and source=Notarized Developer ID. If it says rejected, the line after it tells you why. source=Developer ID without "Notarized" means the app is signed but was never notarized, or the ticket can't be found.

3. Is the ticket stapled?

xcrun stapler validate MyApp.app

Run it on the .dmg or .pkg too if that's what you ship. The validate action worked! means the notarization ticket is attached, so Gatekeeper can verify the app without contacting Apple.

To see who signed the app and how:

codesign -dvv MyApp.app

Look for an Authority=Developer ID Application: Your Name (TEAMID) line, a Timestamp= line (not Signed Time=, which means there's no secure timestamp), and flags=0x10000(runtime), which is the hardened runtime.

The causes, most common first

1. Something changed the bundle after you signed it

This is the classic cause of "damaged" on an app that was signed correctly. A code signature seals the contents of the bundle. Add a file, edit a file, or remove one afterwards and the seal no longer matches.

The usual ways this happens:

  • A build step runs after codesign: copying in a config file, writing a version number into Info.plist, stripping binaries, or bundling a helper downloaded at the last minute
  • The app was zipped with a tool that doesn't preserve symlinks or macOS metadata. Frameworks inside an app are full of symlinks, and flattening them breaks the signature
  • The archive was unpacked and repacked on Windows or Linux somewhere in your CI pipeline
  • The app writes into its own bundle at runtime (logs, caches, a license file), which breaks the seal on the user's machine after first launch

The fix is to make signing the last thing that touches the bundle, and to package with tools that keep it intact. To make a zip, Apple's documentation says to use ditto:

ditto -c -k --keepParent MyApp.app MyApp.zip

And store anything the app writes at runtime in ~/Library/Application Support, never inside the .app.

2. The app isn't signed, or is only ad-hoc signed

Plenty of build tools produce an unsigned or ad-hoc signed app by default when no certificate is configured. This is the usual story for Electron, Tauri and Flutter apps built in CI without signing secrets: the build succeeds, the artifact looks fine, and every user who downloads it on an Apple silicon Mac is told it's damaged.

Check which certificates you have:

security find-identity -v -p codesigning

You need one that starts with Developer ID Application:. It comes with the Apple Developer Program. An Apple Development or Mac App Distribution certificate won't do: Apple's notary service only accepts apps signed with a Developer ID certificate.

3. Nested code isn't signed, or was signed in the wrong order

Every executable inside the bundle needs its own signature: frameworks, dylibs, helper apps, XPC services, command-line tools, and native Node modules. Sign from the inside out, deepest items first and the app itself last, with a secure timestamp and the hardened runtime on each:

codesign --force --timestamp --options runtime \
  --sign "Developer ID Application: Your Name (TEAMID)" \
  MyApp.app/Contents/Frameworks/Some.framework

codesign --force --timestamp --options runtime \
  --entitlements MyApp.entitlements \
  --sign "Developer ID Application: Your Name (TEAMID)" \
  MyApp.app

It's tempting to sign everything in one go with --deep. It applies the same options and entitlements to every nested item, which is rarely right, so use it for verifying and sign each item explicitly.

4. The app was never notarized

Signing isn't enough on its own. Since macOS 10.15, Gatekeeper expects software downloaded from outside the Mac App Store to be notarized: you upload the build to Apple, an automated service scans it, and it issues a ticket.

xcrun notarytool submit MyApp.dmg --keychain-profile "notary" --wait

If the result is Invalid, read the log. It lists every file that failed and why:

xcrun notarytool log <submission-id> --keychain-profile "notary"

The messages are specific. The common ones, from Apple's own list:

Message in the log What to do
The signature of the binary is invalid. The bundle changed after signing, or a nested item is unsigned. See causes 1 and 3.
The binary is not signed with a valid Developer ID certificate. Sign with Developer ID Application, not a development or App Store certificate.
The signature does not include a secure timestamp. Add --timestamp to every codesign call.
The executable does not have the hardened runtime enabled. Add --options runtime.
The executable requests the com.apple.security.get-task-allow entitlement. That's a debug entitlement. Build for release, or remove it from the entitlements file.

5. The ticket isn't stapled

After notarization succeeds, attach the ticket to what you ship:

xcrun stapler staple MyApp.dmg

Without it, Gatekeeper has to ask Apple's servers whether the app is notarized, and a user who's offline or behind a strict firewall gets blocked. You can staple apps, disk images and installer packages. You can't staple a zip, so if you ship a zip, staple the .app first and zip it afterwards.

6. You notarized one thing and shipped another

The ticket belongs to the exact files Apple scanned. If your pipeline notarizes the app, then rebuilds it, re-signs it or adds a file while making the disk image, the shipped copy doesn't match.

Apple's guidance for nested containers is to sign each layer and notarize only the outermost one. So for an app on a disk image: sign the app, build the DMG, sign the DMG, notarize the DMG, staple the DMG. Then upload that file and nothing else. There's more on the two container formats in DMG vs PKG.

A release order that doesn't break

# 1. Sign nested code, then the app (inside out)
codesign --force --timestamp --options runtime \
  --entitlements MyApp.entitlements \
  --sign "Developer ID Application: Your Name (TEAMID)" MyApp.app

# 2. Check the signature before going further
codesign -vvv --deep --strict MyApp.app

# 3. Package and sign the container
hdiutil create -volname "MyApp" -srcfolder MyApp.app -ov -format UDZO MyApp.dmg
codesign --timestamp --sign "Developer ID Application: Your Name (TEAMID)" MyApp.dmg

# 4. Notarize and staple the container
xcrun notarytool submit MyApp.dmg --keychain-profile "notary" --wait
xcrun stapler staple MyApp.dmg

# 5. Check what Gatekeeper will say
spctl -vvv --assess --type open --context context:primary-signature MyApp.dmg

Then do the real test: upload the DMG, download it in a browser, and open the app from it.

If you run this in CI, the guide to notarized macOS releases in CI has a complete workflow, including how to store the certificate and the notary credentials as secrets.

What to tell users who already have the broken build

Ship a fixed build first. That's the answer for everyone who hasn't downloaded yet.

For someone stuck right now, the honest instructions are: try to open the app once, then go to System Settings, Privacy & Security, scroll to the Security section and click "Open Anyway". If macOS doesn't offer that button, which happens when the signature is broken and not just missing, the remaining option is to remove the quarantine flag in Terminal:

xattr -dr com.apple.quarantine /Applications/MyApp.app

Treat that as an apology, not as documentation. Asking customers to paste a Terminal command that switches off a security check costs you sales and trains them to do the same for the next app that asks. If it's in your README today, it's a sign the build pipeline needs fixing.

Updates can trigger it too

A first install that opens cleanly doesn't mean you're done. An update replaces the app on disk, and the new copy gets verified as well. If your update archive is built by a different step than your first-download archive, check both. And if an updater patches files in place, the signature of the result has to be valid, or users who were fine yesterday get "damaged" today.

This is one reason to treat signing, notarization, packaging and the update feed as one pipeline with one output. LicenseSeat hosts that output for apps sold outside the App Store: it serves your signed builds and update feed to licensed customers, alongside the license key checks. It charges a flat monthly fee and takes 0% of your revenue. The guide to licensing macOS apps covers the whole path from build to paid customer.

Common questions about the "damaged" message

Why does macOS say my app is damaged when the file is fine?

Because the app carries the quarantine flag and its code signature didn't pass Gatekeeper's check. macOS uses the "damaged" wording for apps that are unsigned, ad-hoc signed, or whose signature no longer matches the bundle's contents, even though the download itself is complete.

Why does my app open on my Mac but not on a user's Mac?

A locally built app has no quarantine flag, so Gatekeeper never checks it. Your users' copy was downloaded, so it's flagged and checked. Download your own release in a browser to reproduce what they see.

Do I need to pay Apple to fix this?

Yes, in practice. A Developer ID certificate and notarization both require membership of the Apple Developer Program, which costs 99 USD a year. Without them, every user has to bypass Gatekeeper by hand.

Is signing enough, or do I need notarization too?

You need both. A Developer ID signature identifies you; notarization is Apple's automated scan of that signed build. Since macOS 10.15, a signed app that isn't notarized is still blocked on first launch.

Does notarizing the DMG cover the app inside it?

Yes. Apple's guidance for nested containers is to sign each layer and notarize only the outermost one. Notarizing the disk image covers the signed app inside. Staple the ticket to the disk image afterwards.

Why did my app start showing "damaged" after an update?

Either the update archive was packaged differently from the first download and broke the signature, or the app or its updater modified files inside the bundle. Verify the updated app with codesign -vvv --deep --strict on a machine that received the update.

Can I fix it without rebuilding?

Not for your users. You can re-sign and re-notarize an existing build if the code is unchanged, but the file customers download has to be replaced either way.