Troubleshooting · Gatekeeper
Fixing “App is damaged and can’t be opened” on macOS
A Mac app works on its developer’s machine, but a customer downloads it and sees “App is damaged and can’t be opened.” That message is not a diagnosis you can solve with one universal command. Start by identifying the warning and the source, then inspect the exact app being distributed. The goal is a trustworthy release—not weaker security on the customer’s Mac.
By Francisco Cantu ·
1. Read the exact warning before doing anything
- “App is damaged and can’t be opened”
- The app may be damaged or modified, including an invalid signature or a corrupted download. The wording alone does not prove malware, nor does it prove the app is safe.
- “Developer cannot be verified” or “Apple cannot check it for malicious software”
- macOS could not establish the required trust. This is different from a finding that the software contains malware. The developer should investigate signing and notarization.
- “Will damage your computer” or a malware warning
- Do not open the app or try to bypass the warning. Follow Apple’s guidance and contact the developer or your administrator.
- “Downloaded from the Internet”
- A routine first-open confirmation is not the same as a damaged-app or malware alert. Only proceed if you intended to download the app and trust its source.
Download quarantine metadata helps macOS recognize Internet-delivered software for assessment. Its presence is normal. Deleting it is not a repair for a corrupt bundle or a broken signature, and can hide the customer’s real installation path during testing.
2. If you’re installing someone else’s app
- Confirm the source. Use the developer’s official website, not a mirror or a link from an unexpected message. Stop if the source or app name is suspicious.
- Download a fresh copy. Remove the failed download and extract a new official archive. Do not merge it with an old app bundle or edit its contents.
- Check version and compatibility. Confirm your macOS version and Mac architecture are supported.
- Contact support if it persists. Send the exact alert, app version, macOS version, and download URL. Ask for a correctly signed and notarized build.
- For a managed Mac, check with your administrator. Organizational policy may impose additional restrictions.
Apple documents a deliberate “Open Anyway” exception for some trusted apps that cannot be verified. It is not a fix for the damaged-app warning and not proof of safety. This guide does not recommend overrides or Terminal security-bypass commands; never override a malware warning.
A developer asking every customer to disable Gatekeeper or remove quarantine has not demonstrated that the release is healthy. Ask them to fix and validate the artifact instead.
3. Developers: reproduce the browser download
Download the same public URL your customer used through a browser. Extract the archive into a clean location and launch it normally. A build launched from Xcode, copied over a local filesystem, or tested after removing quarantine does not exercise the same path.
Record the version, build number, artifact filename, URL, and exact warning. Compare the hosted archive to the artifact you intended to publish. If you publish a checksum, generate it from the final archive and ensure it matches the downloaded copy.
Compare final archive checksums on macOS
shasum -a 256 "MyApp-release.zip"
shasum -a 256 "MyApp-downloaded.zip"Matching checksums establish that the two files match; they do not establish safety. A checksum distributed from the same compromised source is not an independent trust guarantee.
4. Inspect signatures and the notarization ticket
Read-only checks on the extracted app
# Replace this path with the app you actually downloaded.
codesign --verify --deep --strict --verbose=2 "/Applications/MyApp.app"
codesign --display --verbose=4 "/Applications/MyApp.app"
spctl --assess --type execute --verbose=4 "/Applications/MyApp.app"
xcrun stapler validate "/Applications/MyApp.app"- Signature verification: look for an invalid seal or a named nested component. Verify the framework or helper reported in the error too.
- Signing identity: confirm this is the intended Developer ID release, not an ad-hoc or development build accidentally uploaded.
- Gatekeeper assessment:
spctlasks the local system’s policy to assess the app. macOS version, local policy, network access, and ticket availability can affect the result. - Staple validation: this checks an attached ticket. A missing staple alone does not prove notarization failed; Gatekeeper can also retrieve a published ticket online. Validate the accepted submission separately.
These commands diagnose, not repair. They also do not prove an app is harmless. For a flat installer package, use package-appropriate checks such as pkgutil --check-signature; do not assess every deliverable as if it were an app bundle.
5. Repair the cause and produce a new artifact
If the signature is invalid: find what changed after signing. Common culprits include editing an Info.plist, rewriting resources, replacing an executable, or shipping a partially merged bundle. Rebuild from a clean source state, sign nested code correctly, then sign the app. Do not patch a signed app in place and assume its original ticket remains meaningful.
If notarization was rejected: fetch Apple’s submission log and resolve the actual errors. Inspect the specific binary, entitlement, or signing identity named in the log. A submission ID or “uploaded successfully” message does not mean the submission was accepted.
If the accepted app lacks a staple: staple the supported artifact, validate it, then make the final download. ZIP archives cannot be stapled directly; staple the enclosed app before creating the final ZIP.
If the hosted file is wrong: fix the upload path or stale cached artifact. Use versioned archive names and check what the public URL returns. If already-shipped app contents change, issue a new build and notarize the repaired release rather than quietly substituting an incompatible artifact.
Use the notarization errors guide for log-based fixes. Neither codesign --deep --force nor switching off system security is a substitute for the correct signing pipeline.
6. Verify the repaired release before announcing it
- Verify the finished app’s signature and accepted notarization result.
- Validate the staple on the supported deliverable.
- Upload the final archive and download it through the public URL.
- Test extraction and first launch on a clean Mac or account, ideally without relying on an already-cached trust decision.
- Test on supported macOS versions and architectures.
- If it is a Sparkle update, upgrade a real older installation and check the new version launches.
Keep the reproduction steps and results with your release record. If the warning still differs between environments, collect the exact platform and policy differences rather than declaring the problem fixed after a single local launch.
Simplify your next release with HarborPilot.
HarborPilot can take repetitive build, signing, notarization, stapling, and Sparkle packaging steps off your checklist. Pair that automation with a browser-download test so customers receive the release you validated—not instructions to weaken their Mac’s defenses.
Sources and further reading
- Apple: Safely open apps on your Mac
- Apple: If an app has been modified or damaged
- Apple Platform Security: Gatekeeper and runtime protection
- Apple: Resolving common notarization issues
- Apple: Notarizing macOS software before distribution
Service limits and Apple requirements can change. Check the linked documentation before publishing. HarborPilot is not affiliated with Apple, Cloudflare, or the Sparkle project.