Troubleshooting · Apple notarization

Apple Notarization errors and how to fix them (2026 update)

A failed notarization is easier to fix when you start with Apple’s submission log rather than repeatedly rebuilding. This November 2026 reference walks through credentials, signatures, packaging, and stapling using notarytool. The date marks this guide’s review—not a claim that Apple introduced new rules this year.

By Francisco Cantu ·

First, identify which step failed

Code signing establishes the developer identity and protects code integrity. Notarization is Apple’s separate automated check of submitted software; it is not Mac App Store App Review. Stapling attaches the accepted ticket to a supported deliverable so it is available locally.

  • Upload or authentication failed: Apple may not have created a submission. Fix credentials or transport first.
  • In Progress: a submission is pending, not rejected. Check the existing submission instead of creating duplicates.
  • Invalid: retrieve the log and fix the reported paths and messages.
  • Accepted, but stapling failed: troubleshoot the ticket and artifact, not the signing pipeline from scratch.

Use a current supported Xcode toolchain and notarytool. Older instructions based on altool are obsolete for notarization uploads. Check xcrun notarytool help against your installed toolchain.

1. Retrieve the submission status and log

These commands assume you already have a valid Keychain credential profile. Replace the profile and submission ID with your own values. No private key or password belongs in a bug report.

Read Apple’s result

xcrun notarytool info "SUBMISSION_ID" \
  --keychain-profile "NOTARY_PROFILE"

xcrun notarytool log "SUBMISSION_ID" \
  --keychain-profile "NOTARY_PROFILE" \
  "/tmp/notary-log.json"

Open the JSON log and read each issue’s path and message. One app can contain several failing frameworks or helper binaries. Fix all reported failures, not only the main executable. Save the submission ID so you can distinguish this attempt from an older result.

2. Fix authentication before rebuilding

An unauthorized response or invalid Keychain profile is not evidence that your app is malformed. Check the profile name, account/team authorization, and whether the credentials are still valid. For a team App Store Connect API key, verify the key ID, issuer ID, and local key file belong together.

Store a team API key in Keychain

xcrun notarytool store-credentials "NOTARY_PROFILE" \
  --key "/path/to/AuthKey_KEYID.p8" \
  --key-id "KEY_ID" \
  --issuer "ISSUER_ID"

This template is for a team API key. Individual keys and Apple ID credentials have different options; follow the tool’s help for your credential type. Keep the .p8 file private and never paste its contents into logs or support emails.

If a submission remains pending, check Apple’s developer system status and query that submission again later. A long wait alone does not mean rejection.

3. Resolve invalid signatures and nested code

If the log reports an invalid signature, verify the exact app that you packaged—not a different local build.

Inspect the signed app

codesign --verify --deep --strict --verbose=3 "/path/to/MyApp.app"
codesign --display --verbose=4 "/path/to/MyApp.app"
security find-identity -v -p codesigning

For outside-store distribution, check that the app uses the intended Developer ID Application identity rather than an ad-hoc or development signature. Check certificate validity and the signing team. Apple’s log may point to a bundled framework, XPC service, or command-line helper with its own signing problem.

Sign nested code correctly as part of your build/export process and the outer bundle afterward. Do not use --deep as a blanket signing repair: it is useful here for verification, but does not replace deliberate nested signing.

Do not edit the bundle after signing. Copying resources in, patching a binary, or changing Info.plist can invalidate the signature. Rebuild and sign the final bundle, then package it without altering its contents.

4. Check hardened runtime and timestamps

When Apple’s log reports a missing hardened runtime or secure timestamp, correct your release signing configuration. In Xcode, check the Release configuration’s Hardened Runtime capability and Developer ID export settings. The diagnostic display above helps inspect signing flags and timestamp information.

Audit every executable mentioned in the log, including helpers from third-party dependencies. Replace or rebuild a dependency that does not meet the signing requirements. Adding broad runtime exceptions or unrelated entitlements is not a substitute for fixing the reported issue.

Keep entitlements narrow and specific to your app. A workaround that launches locally is not proof of a safe or accepted distribution build.

5. Submit the right archive or installer

Submit a supported ZIP archive, disk image, or installer package. For a ZIP-based app release, preserve the app bundle’s structure and symlinks:

Package and submit a signed app

ditto -c -k --sequesterRsrc --keepParent \
  "/path/to/MyApp.app" "/path/to/MyApp.zip"

xcrun notarytool submit "/path/to/MyApp.zip" \
  --keychain-profile "NOTARY_PROFILE" --wait

For an installer, the package needs a Developer ID Installer signature; that is different from the Developer ID Application certificate used for the app inside it.

Verify an installer signature

pkgutil --check-signature "/path/to/MyApp.pkg"

Look for the correct Developer ID Installer identity and a trusted timestamp. Build and sign the package with the proper packaging tool, and inspect its contained app too. Renaming an unsupported file to .zip or .pkg does not make it valid.

6. Staple the accepted artifact—not the ZIP

After Apple reports Accepted, staple the ticket to the app, disk image, or supported installer. A ZIP itself cannot be stapled. For a ZIP workflow, staple the submitted app bundle and then create the final download archive from that stapled app.

Staple and validate the app

xcrun stapler staple "/path/to/MyApp.app"
xcrun stapler validate "/path/to/MyApp.app"
spctl --assess --type execute --verbose=4 "/path/to/MyApp.app"

If stapling fails, confirm the submission was accepted and you are using the matching artifact. Check connectivity and Apple’s troubleshooting guidance. Do not rebuild or mutate the app between the accepted submission and stapling.

Apple also publishes notarization tickets online for Gatekeeper to find. Stapling improves local ticket availability; its failure is not the same thing as Apple rejecting the submission.

7. Test the file your users will actually download

After stapling and final packaging, generate the Sparkle signature and appcast for the final archive. Changing the archive afterward invalidates its Sparkle signature.

  • Download the release from its real public URL on a clean test Mac.
  • Check Gatekeeper behavior using the downloaded artifact, not only your local build.
  • Test an actual Sparkle upgrade from an older signed version.
  • Keep the accepted submission ID and log with your private release records.

For updater integration, see the Sparkle setup guide. Code signing, notarization, and Sparkle signing are distinct checks; passing one does not automatically pass the others.

Simplify your next release with HarborPilot.

HarborPilot brings the repeated build, signing, notarization, stapling, and Sparkle packaging steps into one release workflow. Your keys stay in Keychain and the work runs on your Mac. It reduces manual handoffs, but does not bypass Apple’s checks or repair invalid app code for you.

Sources and further reading

Service limits and Apple requirements can change. Check the linked documentation before publishing. HarborPilot is not affiliated with Apple, Cloudflare, or the Sparkle project.