macOS App Notarization Failed: How To Fix notarytool in 2026?

Start by checking the notarytool status and log; do not repeatedly submit the same artifact. Repair the final ZIP, DMG, or PKG only after you know whether the failure occurred during authentication, signing, packaging, submission, ticket stapling, or Gatekeeper validation. An Accepted result is not the finish line: you still need stapler, Gatekeeper checks, and an install test in an independent environment.

This guide is for independent developers distributing outside the Mac App Store with a Developer ID certificate, maintainers running notarization on a remote Mac or CI session, and small teams shipping apps with plugins, helper tools, DMG images, or PKG installers.

This week’s action: preserve the failed submission record first, reproduce the check against the exact release artifact, then promote only a build that passes submission, stapling, and user-side installation.

The release timeline

A redacted release can fail in two different ways: Invalid may appear after submission, or Accepted may appear while users still receive a Gatekeeper warning. Those outcomes look similar when viewed only from the release dashboard, but they require different actions.

Keep these stages separate:

Apple’s current command-line notarization workflow uses notarytool. Apple’s migration guidance also states that altool stopped being accepted by the notarization service on November 1, 2023, so a script still built around the older submission path needs a deliberate migration rather than a blind retry. See Apple’s notarytool migration guidance.

The evidence checkpoint

Before removing a certificate, changing credentials, or signing again, save the evidence that can explain the failure. Store the submission ID, the complete terminal output, the SHA-256 digest of the submitted file, the selected Xcode path, and the exact command used to create the archive and package.

Do not store secrets in the evidence bundle. Redact the Apple Account identifier, Team ID, certificate identity, submission ID, Bundle ID, local path, host address, API key contents, and private-key locations before sharing logs with a teammate. Keep the private unredacted copy in a restricted location if your release policy allows it.

A release record should connect the artifact to the submission:

The most common hidden cost is testing the wrong object. An app inside a DMG may be fixed while the DMG being uploaded is an older copy. A ZIP may pass local inspection while automation submits a different path. A PKG may contain a postinstall tool that was never checked as part of the app review.

Which file should you inspect first after notarytool reports Invalid?
Inspect the exact ZIP, DMG, or PKG referenced by the submission, not only the Xcode project or the original .app inside an archive. If the digest does not match the release record, stop debugging that submission and recreate the evidence trail.

The artifact inspection milestone

Start with the innermost executable and work outward. Inspect the main app, embedded frameworks, plug-ins, login items, helper tools, XPC services, and any other executable content. A valid outer signature cannot compensate for a missing or invalid signature inside the bundle.

For a signed app, check the signing identity, Hardened Runtime, secure timestamp, entitlements, and nested code. The result should correspond to the distribution path you actually use. Mac App Store submission and direct Developer ID distribution are separate workflows; an App Store signing setup is not a substitute for a Developer ID release identity.

Apple’s macOS notarization requirements describe the relationship between signing, Hardened Runtime, notarization, and distribution. Use the official requirements as the authority when a local shortcut conflicts with the release workflow.

Typical inspection commands include:

codesign --verify --deep --strict --verbose=4 "Release.app"
codesign -dv --verbose=4 "Release.app"
codesign -d --entitlements :- "Release.app"
spctl --assess --type execute --verbose=4 "Release.app"

The --deep option is useful for verification, but it should not become an excuse to hide bundle structure. A recursive signing command can produce a superficially clean result while leaving you unsure whether the correct helper, framework, or plug-in was signed with the intended identity.

Look specifically for these boundaries:

• A get-task-allow entitlement left in a direct-distribution build.
• Entitlements whose format or values do not match the provisioning and release design.
• A nested executable signed with the wrong certificate type.
• A framework or helper modified after its parent app was signed.
• A missing secure timestamp.
• A bundle file changed after signing.
• A DMG or PKG recreated from an older app copy.
• A package script that installs executable content not covered by the original validation.

Signing is not a one-time label. If you change an embedded framework, helper, resource that affects the signed bundle, or package payload after verification, repeat the required signing and inspection steps. Do not staple or publish an artifact that no longer matches the inspected content.

Why can a signed macOS app still fail notarization?
Because “signed” does not mean “correctly signed for every nested object and distribution condition.” The failure may be a missing secure timestamp, an invalid entitlement, an unsuitable certificate, an unsigned helper, or a later modification to the bundle. The first useful error path in the notarization log is more valuable than another local signature check.

The notarytool log milestone

For an Invalid submission, retrieve the submission information and log using the submission ID. The exact authentication flags depend on whether your workflow uses an App Store Connect API key, a keychain profile, or another supported credential method. Keep the credential source stable while diagnosing the artifact; changing both the file and authentication method at once removes your comparison point.

A typical retrieval pattern is:

xcrun notarytool info "<REDACTED_SUBMISSION_ID>" \
  --keychain-profile "<REDACTED_PROFILE>"

xcrun notarytool log "<REDACTED_SUBMISSION_ID>" \
  --keychain-profile "<REDACTED_PROFILE>" \
  notarization-log.json

Use the syntax documented for the Xcode toolchain selected on the machine. Do not paste real identifiers into public examples.

How do you find the specific reason after notarytool shows Invalid?
Run notarytool log with the submission ID, open the returned JSON, and fix the first valid error that points to a concrete path or object. An error for a nested helper can make later messages secondary. After the repair, create a new artifact and submit that new artifact instead of reusing the rejected file.

Map the first actionable error to a repair boundary:

Apple’s common notarization issue guidance should take priority over guesses based on a forum status code. A processing delay or temporary service condition may exist, but it should not be treated as the explanation for every Invalid result.

If a submission remains in processing, avoid an uncontrolled retry loop. Check the submission status, preserve the current ID, and review Apple’s service-status information when the delay appears abnormal. Do not claim that a particular queue duration always means a specific fault unless the current official documentation confirms it.

The inside-out rebuild

Once the error is known, repair from the smallest affected executable outward:

• Fix the source, build setting, entitlement, or packaging input.
• Rebuild the affected binary or helper.
• Sign the innermost executable and verify it.
• Sign the containing framework, plug-in, service, or app.
• Re-run signature and entitlement checks.
• Export or package a new release artifact.
• Inspect that final container before submission.
• Submit the new artifact and record its new submission ID.

This order prevents an outer signature from hiding a damaged inner component. It also gives you a clean rollback point: preserve the rejected artifact and the repaired artifact as separate files.

ZIP, DMG, and PKG are not interchangeable:

Apple’s Mac software packaging documentation explains the packaging workflow. If a PKG installs additional executable content, treat that content as part of the release design. Do not assume that notarizing an app automatically proves the behavior of every installer payload or script.

For a DMG, submit the final DMG that users will download, not merely the app extracted from it. For a ZIP, make sure the archive path used by automation is the newly created file. For a PKG, check the installer package after all scripts and payloads are included. If a workflow produces several separately distributable artifacts, track their submission records separately rather than assuming one accepted object covers all of them.

Apple’s custom notarization workflow documentation is useful when adapting these stages to scripts or CI. Use it to keep submission, status retrieval, log collection, and post-submission validation as explicit steps instead of hiding them inside one opaque packaging command.

The accepted-to-release gate

Accepted means the notarization service approved the submitted content. It does not mean the ticket has been attached to the file, that the download is intact, or that a clean user environment will accept the release.

Run the appropriate stapling command against the final distributable object:

xcrun stapler staple "Release.app"
xcrun stapler validate "Release.app"

For a DMG or PKG, apply the command to the object you plan to distribute. Then run Gatekeeper assessment against that same object or the installed app, according to the release type:

spctl --assess --type execute --verbose=4 "Release.app"

Does Accepted mean you can skip stapler?
No. For a release that should work without depending on an online ticket lookup, staple the approved ticket when the format and workflow support it, validate the stapled object, and test the exact download. An accepted submission that fails stapling is a release-readiness problem, not a reason to declare the release complete.

Perform the final test on a Mac that does not contain your development cache, previous app copy, or local signing assumptions. Download the same file a customer receives. Test with restricted or unavailable network access where your distribution policy requires offline trust. Confirm the file digest before installation so you do not accidentally validate an older artifact.

Gatekeeper behavior can also differ between an app opened from a local build folder and an app downloaded through the real distribution path. That is why a clean-machine test belongs after stapling, not only after the local codesign command.

The remote Mac hardening milestone

A local notarization success followed by a remote failure usually points to environment drift rather than a mysterious change in the app. Compare the selected Xcode path, credential profile, keychain access, working directory, packaging script, and session type.

Why can local notarization pass while automation on a remote Mac fails?
The two sessions may use different Xcode toolchains, keychain profiles, environment variables, file paths, or package copies. A graphical login and an SSH session can also expose different keychain availability and working-directory assumptions. Log those inputs before replacing credentials or rebuilding the host.

Make the remote workflow explicit:

• Pin the Xcode developer directory with xcode-select or DEVELOPER_DIR.
• Define the archive, export, package, and submission paths rather than relying on the current directory.
• Use a controlled keychain profile or supported API-key method.
• Record the selected toolchain and credential profile with every release.
• Link the artifact digest, submission ID, log file, and release tag.
• Add bounded polling, timeout, retry, and manual-stop conditions.
• Preserve failed artifacts instead of overwriting them.
• Test both SSH and graphical sessions if both are part of the operation.
• Simulate a disconnected session and a host restart before trusting unattended publishing.
• Keep a documented rollback to the last accepted artifact.

When moving Developer ID private keys, first confirm export permissions, access controls, and a recovery copy. Removing an old identity before the replacement is verified can stop existing releases from being reproduced. Changing credentials during a notarization investigation can also create a second failure layer, so change one variable at a time and record the rollback path.

If your current developer computer cannot reliably retain the private key, selected Xcode toolchain, and long-lived notarization logs, a permission-isolated remote Mac can be a better release boundary. Review the available VMSPIN Mac plans only after you have identified the local failure layer. The machine should first prove the complete non-production path: Build, Archive, Export, Sign, Package, Submit, Accepted, Staple, Gatekeeper, and clean installation.

For a temporary release window or a test environment, VMSPIN remote Mac access can avoid dedicating a purchased Mac to a pipeline that runs intermittently. It is less suitable when you need guaranteed physical peripherals, a permanently local build cache, or a long-term heavy workload whose total rental cost exceeds owning hardware.

A remote host is not a substitute for diagnosis. Move the workflow only after you know which artifact and credential path work. Then use the first week to validate interruption recovery, host restart behavior, session differences, and the next real release.

The shortest reliable path is therefore a timeline: preserve the submission, inspect the final artifact, read the first actionable log error, rebuild from the inside out, staple and validate the accepted object, and test the customer download on a clean Mac. If your current setup loses the Developer ID key, changes Xcode paths between sessions, or drops the logs when a remote connection ends, keeping the release chain on a controlled VMSPIN Mac can be more dependable than repeatedly repairing an opaque local or improvised CI environment. Start with a non-production version, retain a rollback artifact, and promote only after the entire user-facing path passes.