Resolving Common Notarization Issues

If the Apple notary service encounters any problems while notarizing your app, it reports those errors in the log files, as described in Check the Status of Your Request. Fix any problems reported by the service and notarize your app again.

Before you can notarize an app, you must first code sign it. If you don’t, or if you make a modification to the bundle after signing, notarization fails with the following message:

The signature of the binary is invalid.

To debug signing issues, use the codesign utility to test the signature:

$ codesign -vvv --deep --strict /path/to/binary/or/bundle

Use the vvv flag to perform a verification with elevated verbosity. You use the deep flag to ensure the utility checks nested code content. The strict flag increases the restrictiveness of the validation to match that required by notarization. See the codesign man page for more information about these flags and how to interpret the output.

You can only notarize apps that you sign with a Developer ID certificate. If you use any other certificate—like a Mac App Distribution certificate, or a self-signed certificate—notarization fails with the following message:

The binary is not signed with a valid Developer ID certificate.

To learn about managing your signing certificates in Xcode, see Manage Signing Certificates.

Additionally, you can use the spctl utility to determine if the software to be notarized will run with the system policies currently in effect:

$ spctl -vvv --assess --type exec /path/to/application

Add the --raw option to generate a more detailed output in the form of a property list.

By default, Xcode doesn’t include a secure timestamp as part of the app’s code signature during the build process. Instead, it adds a secure timestamp only during the archive (as of Xcode 10.2) and export workflows. If you use a custom export process, notarization might fail with the following message:

The signature does not include a secure timestamp.

In this case, be sure to add a secure timestamp by adding the --timestamp flag to your OTHER_CODE_SIGN_FLAGS build setting, or by using the flag directly with the codesign utility if you sign manually, as described in the previous section.

You can check if a binary has a secure timestamp with the following command:

$ codesign -dvv /path/to/binary/or/bundle

The dvv flag tells codesign to display information about the code at the given path with elevated verbosity. For a binary with a secure timestamp, the output of this command includes a Timestamp value with a corresponding date. Alternatively, the presence of Signed Time in the output indicates the binary doesn’t have a secure timestamp.

When you create a new macOS project, Xcode automatically sets the target’s CODE_SIGN_INJECT_BASE_ENTITLEMENTS build setting to YES. This setting tells Xcode to add the com.apple.security.get-task-allow entitlement to your app at build time. This entitlement facilitates debugging on a system that uses System Integrity Protection (SIP) by circumventing certain security checks.

However, this poses a security risk for a shipping app, because it can allow an attacker to inject code at runtime. As a result, Xcode automatically strips the entitlement from your app when you export and sign it using the standard workflow. If you use a custom workflow and fail to remove the com.apple.security.get-task-allow entitlement, notarization fails with the following message:

The executable requests the com.apple.security.get-task-allow entitlement.

To avoid receiving this error message, archive (as of Xcode 10.2) or export your app directly from Xcode, or set the CODE_SIGN_INJECT_BASE_ENTITLEMENTS build setting to NO before building your app for distribution. But only change the build setting when you’re done debugging and ready to distribute, because doing so makes it impossible to debug the binary on a system that uses System Integrity Protection.

Because of significant differences in the way code signing works prior to macOS 10.9 (see Code Signing Changes in OS X Mavericks 10.9), notarization only works for binaries linked against macOS 10.9 or later. If you use an older SDK, notarization fails and reports an issue with the following message:

The binary uses an SDK older than the 10.9 SDK.

Using a newer SDK doesn’t affect your binary’s compatibility with earlier versions of macOS. Instead, version compatibility depends on the app’s deployment target, as described in Edit deployment info settings.

Enable the hardened runtime capability as described in Enable hardened runtime (macOS). This adds security restrictions to your app by default while allowing you to ask for specific exceptions as needed. If you don’t enable the hardened runtime, notarization fails and reports an issue with the following message:

The executable does not have the hardened runtime enabled.

Hardened runtime is available in the Capabilities pane of Xcode 10 or later, but you can enable the feature manually using earlier versions of Xcode, as long as you’re on macOS 10.13.6 or later. To do this, add the following flag to the OTHER_CODE_SIGN_FLAGS build setting:

--options=runtime

If you need exceptions, manually add the entitlements to your app’s entitlements file. If you enable hardened runtime manually using an earlier version of macOS, make sure that you also test your app running on macOS 10.14 or later.

You can resolve a few common stapler issues by upgrading your tools. In particular, if you see error -68 on macOS 10.13.x, you can resolve the issue by upgrading to macOS 10.14 or later. Alternatively, run the following command once to clear the Valid cache:

$ sudo killall -9 trustd; sudo rm /Library/Keychains/crls/valid.sqlite3

If you see error -73 while using Xcode 10, you can resolve this issue by upgrading to Xcode 10.1 or later. Also, in this case, check to ensure that the disk image or flat installer package you’re notarizing is writable so you can attach the ticket to the package with the stapler utility.

See the stapler man page for a discussion of other exit codes.