Unity package damaged Mac

by

Summary

The reported issue is a false positive “package is damaged” error on macOS when downloading Unity Hub or Unity Editor installers. This is not actual corruption; it is a macOS security quarantine flag applied to unsigned or notarized software downloaded from the web. This flag triggers Gatekeeper and Finder checks that report the file as damaged even when the bits are intact. The immediate fix is to clear the quarantine attribute using xattr or to right-click Open the app to allow it once in Security & Privacy settings.

Root Cause

The root cause is a macOS extended attribute (com.apple.quarantine) attached by the browser or Finder to files downloaded from the internet. This attribute triggers Gatekeeper validation. If the application is:

  • Not code-signed by an Apple-recognized Developer ID,
  • Not notarized by Apple (a post-build malware scan),
  • Or the notarization ticket is missing/unavailable,

macOS reports the file as “damaged” rather than explaining it is blocked for security. In Unity’s case, older Unity Hub releases and some standalone Editor installers were shipped without full notarization, causing this behavior on macOS Catalina and later.

Why This Happens in Real Systems

macOS enforces App Sandbox and Gatekeeper policies to protect users. The quarantine flow works like this:

  • A download from a browser adds com.apple.quarantine to the file.
  • When opened, LaunchServices checks code signature and notarization.
  • If the binary is unsigned or fails notarization, macOS blocks execution.
  • Finder displays “XYZ is damaged and can’t be opened. You should move it to the Bin.” This message is misleading; it usually means “blocked,” not corrupted.

Enterprise or CI pipelines often encounter this when:

  • Building on Mac and distributing internally without a signed installer.
  • Mirroring installers on internal artifact servers that strip metadata.

Real-World Impact

  • Blocked developer productivity: Teams cannot install required Unity versions, halting onboarding and builds.
  • Support burden: Repeated downloads, false corruption reports, and wasted bandwidth.
  • Policy violations: Users disabling SIP or Gatekeeper globally (“disable security to fix”), increasing malware risk.
  • Release confidence: “Damaged” errors erode trust in official distribution channels, even when the build is valid.

Example or Code

The following commands diagnose and fix the quarantine attribute without disabling security globally:

# Check quarantine attribute
xattr -l "Unity Hub.app"

# Clear quarantine to allow execution (safe, explicit whitelist)
xattr -cr "Unity Hub.app"

# Verify removal
xattr -l "Unity Hub.app"

To allow the app via GUI:

  • Right-click the app and select Open.
  • Go to System Preferences > Security & Privacy > General and click Allow Anyway.

How Senior Engineers Fix It

Senior engineers address this with precision and policy:

  • Immediate: Run xattr -cr on the affected app to clear quarantine and verify via codesign -dv --verbose=4 --deep to inspect signing/notarization status.
  • Verification: Compare checksums against the vendor’s published hash to ensure the file is truly intact (e.g., shasum -a 256 Unity-Hub.dmg).
  • Prevention: Use notarized, signed installers exclusively. For in-house builds, sign with a Developer ID and notarize via Apple’s notarization service.
  • Distribution: Prefer Apple Disk Images (.dmg) with proper signing and attach a com.apple.security.device.client-entitlements profile if required. For CI, create a post-download step that clears quarantine automatically in the runner.
  • Documentation: Provide a standard runbook entry: “If ‘damaged’ appears on macOS, verify checksum, run xattr -cr, and right-click Open; if persistent, contact vendor for a notarized build.”

Why Juniors Miss It

Juniors often misinterpret the error message and take ineffective or risky actions:

  • Re-downloading repeatedly: The error is not due to bit rot; the attribute persists across downloads unless cleared.
  • Assuming file corruption: They focus on MD5/SHA differences rather than macOS security attributes.
  • Disabling Gatekeeper globally: They run sudo spctl --master-disable, creating security vulnerabilities for the whole machine.
  • Missing vendor context: They don’t check if Unity Hub is notarized or which macOS version introduced stricter Gatekeeper checks.
  • Ignoring right-click Open: They don’t know the macOS workaround for once-off approval, causing repeated frustration.