codesign & Gatekeeper Errors: Troubleshooting Guide
Diagnose macOS application failures by separating code-signature problems from signing identity, entitlements, certificate trust, notarization, quarantine, and Gatekeeper assessment.
A macOS app can fail at several different security layers
A macOS application can fail because its code signature is invalid, because the signing identity or private key is unavailable, because nested code or entitlements do not match the signed application, because certificate trust is a problem, because notarization failed, or because Gatekeeper rejects the distributed artifact.
The most useful diagnostic path is Code Signature → Signing Identity → Entitlements → Certificate/Trust → Notarization → Gatekeeper Assessment. A successful codesign operation does not automatically mean that Gatekeeper will allow the distributed application to run. Developers distributing apps for macOS should also understand the macOS code signing workflow across signing, notarization, and launch assessment.
Find the layer before changing the signing setup
Signing
codesign cannot create or complete the signature.
- Identity unavailable
- Private key inaccessible
- Keychain problems
- Build-user differences
Bundle integrity
The signature exists, but the signed application no longer matches the bundle it covered.
- Invalid signature
- Sealed resource missing
- Nested code failure
- Post-signing modification
Apple security flow
The signature can be valid while notarization or Gatekeeper assessment still fails.
- Entitlement issues
- Notarization rejection
- Gatekeeper rejection
- Quarantine context
Use one sequence for macOS signing and launch failures
The purpose of this sequence is to stop unrelated layers from being mixed together. Start with the application that actually failed, then move outward from its signature toward distribution and Gatekeeper.
Can the app be signed?
If not, inspect the signing identity, private key, Keychain, account, and signing environment.
Does codesign --verify pass?
If not, investigate bundle integrity, nested code, requirements, and the signature itself.
Is the signing identity valid?
Confirm the intended certificate is installed and associated with an accessible private key. If the certificate is present but its key cannot be used, review how code signing private keys are protected in the relevant build environment.
Are nested components signed correctly?
Inspect frameworks, libraries, plug-ins, helper apps, and embedded executables.
Are entitlements correct?
Compare the signed entitlements with the application's intended capabilities and configuration.
Does the certificate chain validate?
Separate signature validity from certificate and trust evaluation. When trust evaluation is the failing layer, inspect the code signing certificate chain rather than assuming the signature itself is malformed.
Does notarization succeed where required?
Review Apple's submission result rather than trying to solve a notarization rejection by repeatedly signing.
Does spctl accept the final artifact?
Use Gatekeeper assessment to determine whether the distributed application is accepted in its current context.
codesign: errSecInternalComponent
This error can appear when the signing process cannot use the required private key or signing identity. The certificate itself may be present, so the investigation needs to distinguish certificate availability from actual private-key access.
Private key
Confirm that the signing certificate has the corresponding private key and that the key is accessible to the process.
Keychain
Check the active Keychain, its lock state, permissions, and the user account performing the build.
Build environment
A local developer session, CI runner, and dedicated build user can have different identity and key-access conditions.
Do not start by replacing the certificate. First establish whether the intended private key is present and accessible in the environment that produced the error.
“No identity found”
When macOS cannot find a usable signing identity, the issue can be the certificate, private key, Keychain, certificate type, or build environment. A signing certificate without its corresponding private key is not enough to create a signature.
Check the local identity
- Is the expected identity listed?
- Is the correct certificate installed?
- Is its private key available?
- Is the command running as the expected user?
Check the CI identity
Repeat the inspection in the build environment. A local Mac may have an identity that was never imported or provisioned correctly on the CI runner.
Also check Keychain access, certificate validity, and the account used by the build process.
Certificate present does not mean the signing key is usable
Certificate present
The certificate can be visible while the corresponding private key is absent or inaccessible.
Key inaccessible
Keychain permissions, lock state, account context, or provider configuration can prevent signing.
Certificate lifecycle
Expiration and revocation are separate certificate-status conditions that should be checked after identity and key availability. A revoked credential has different implications from an expired one, so check the specific certificate revocation status when investigating trust failures.
Diagnostic order: certificate → corresponding private key → Keychain access → certificate validity/status. This prevents a certificate-status problem from being confused with a key-access problem.
“Code object is not signed at all”
An application bundle can contain executable code inside frameworks, libraries, plug-ins, helper applications, and other nested components. Signing only the outer .app does not make an unsigned nested executable valid.
Common cause: the build signs the application and then adds or changes an embedded component. Inspect the component named by the verification output and check when it entered the bundle.
“Code has no designated requirement”
Requirement information is part of how macOS describes and evaluates signed code. An error involving designated requirements should be investigated by inspecting the application's actual signing information rather than treating it as a generic certificate failure.
Inspect the signature
Use the requirement output to understand what identity and code-signing information macOS associates with the application.
Compare the artifact
If a signed application was replaced, rebuilt, or altered after the expected signing step, the requirement information may not describe the artifact you believe you distributed.
“A sealed resource is missing or invalid”
This is a bundle-integrity failure. The application changed after signing, or the signed resource information no longer matches the bundle on disk.
Added files
A file introduced after signing can change the expected bundle contents.
Removed or modified files
Deleting or changing signed resources can cause verification to fail.
Nested code changed
Changing an embedded framework, helper, library, or executable can invalidate the signing hierarchy.
“Code signature invalid”
An invalid signature can originate in the application bundle, a nested component, the signing process, or a post-signing build step. Treat the message as the start of the investigation, not as proof that the certificate is defective.
Bundle modification
The application changed after signing, including resources or embedded components.
Signing hierarchy
A nested framework, library, plug-in, helper, or executable has an invalid or missing signature.
Signing configuration
Identity, entitlements, or the signing process produced an artifact that does not match the intended configuration.
Why the signing hierarchy matters
macOS applications are often signing hierarchies rather than single executable files. The outer application depends on the integrity and signatures of the code it contains.
Signing relationship
App → Frameworks → Libraries → Plug-ins → Helper apps → Executables
The exact bundle structure varies by application, but each executable code component needs to be handled correctly within the final signing hierarchy.
What breaks it
- Changing a nested component after signing
- Adding an unsigned executable
- Replacing a framework
- Packaging a different nested component
- Signing the outer bundle before finalizing its contents
When a verification error names a nested path, follow that path. The outer application may be correctly signed while the named component is the actual failure.
Entitlement errors are not automatically certificate errors
Entitlements describe capabilities associated with signed Apple software. Problems can arise from missing, unexpected, or mismatched entitlements, including configuration related to capabilities such as Keychain access, App Groups, Push Notifications, Associated Domains, and Hardened Runtime settings.
Inspect what was signed
Compare intended capabilities
Check whether the signed entitlements match the application's build configuration and the capabilities it actually needs.
Separate provisioning issues
Where provisioning or profile configuration is relevant, diagnose that configuration separately from the certificate and private key.
Read codesign --verify as a diagnostic report
The useful question is not simply whether codesign failed. It is which component or property failed. Use verification output to narrow the investigation to the bundle, nested code, resource seal, requirements, or entitlements.
Signature inspection
Inspect signing information, identifier, authority information, and other details associated with the application.
Strict verification
Use detailed verification to move from a generic failure toward the specific property or component that needs investigation.
Use each macOS tool for a specific question
codesign -d
Inspect signing information associated with the application or code object.
codesign --verify
Check signature validity, bundle integrity, and verification details.
codesign -dr -
Inspect designated requirement information.
codesign -d --entitlements
Inspect the entitlements associated with the signed application.
security
Inspect identities, certificates, and Keychain-related information.
spctl
Assess whether Gatekeeper accepts the application in its current context.
Separate signature validity from certificate trust
A code signature can be structurally valid while certificate trust, certificate status, or the intended Apple signing identity remains a separate issue. Check the certificate and its trust information after confirming the signature itself.
Certificate
Confirm that the expected Apple signing certificate is being used and that it is within its validity period.
Private key
Confirm the certificate has the corresponding private key and that the signing environment can access it.
Trust and status
Investigate chain, expiration, revocation, and other trust conditions separately from the cryptographic signature.
Do not fix a notarization failure by repeatedly re-signing
| Problem | What it means | First place to investigate |
|---|---|---|
codesign fails | Signing operation failed. | Identity, private key, Keychain, configuration, or signing environment. |
codesign --verify fails | Signature or bundle verification failed. | Bundle integrity, nested code, requirements, or entitlements. |
| Notarization fails | Apple's notarization checks rejected the submitted artifact. | Submission result and the exact final artifact. |
spctl rejects app | Gatekeeper assessment failed. | Assessment output, distribution context, quarantine, signature, and notarization state. |
| Valid signature but warning | The signature itself may be valid while another distribution or security condition remains. | Notarization, Gatekeeper assessment, quarantine, or other context. |
Boundary: signing proves something about the signed code. Notarization and Gatekeeper introduce later stages in the software distribution and launch path.
When notarization fails after signing succeeds
A successful signing command does not establish that Apple's notarization checks will accept the submitted artifact. Diagnose the notarization result against the exact archive or application that was submitted.
Artifact
Check the final bundle contents, nested code, package structure, and whether the submitted artifact is the one you verified locally.
Signing configuration
Review the signing identity, entitlements, nested signatures, and other properties relevant to the submitted application.
Submission result
Use Apple's current notarization response and documentation for the exact rejection reason and current requirements.
Apple's notarization requirements can change. Keep this troubleshooting layer aligned with Apple's current documentation rather than maintaining a permanent list of requirements that may become outdated.
“The application cannot be opened”
This message is not specific enough to identify the root cause. A launch failure can involve an invalid signature, corrupt application, architecture compatibility, quarantine, Gatekeeper assessment, missing components, permissions, or bundle modification.
Integrity
Verify the application and its nested code with codesign.
Compatibility
Check architecture and application compatibility when the signature itself is valid.
Gatekeeper
Assess the exact distributed application with spctl and consider quarantine and distribution context.
Code signing, notarization, and Gatekeeper are distinct
Code signing
Asks whether the code carries valid signing evidence associated with its signing identity and signed configuration.
Notarization and Gatekeeper
Introduce additional distribution and launch assessment layers. A valid signature is therefore not a universal guarantee of acceptance.
“App cannot be opened because the developer cannot be verified”
Do not treat this message as proof that the signature is invalid. The investigation should establish the signing identity, signature validity, notarization state where applicable, Gatekeeper assessment, distribution method, and quarantine context.
Inspect the application
- Verify the signature.
- Inspect the signing identity.
- Check entitlements and nested code.
- Confirm the exact artifact was distributed.
Inspect the launch context
- Check notarization status where required.
- Run Gatekeeper assessment.
- Consider quarantine and download source.
- Compare behavior with the locally built artifact.
Do not make bypassing Gatekeeper the default fix. The goal of troubleshooting is to identify why the distributed application failed assessment.
“Apple cannot check it for malicious software”
This message is not equivalent to “the code signature is invalid.” Investigate the Gatekeeper assessment and the application's distribution context, including notarization, quarantine state, signature, and source.
Signature
Confirm whether the application has a valid signature and expected signing identity.
Notarization
Check whether the final distributed artifact was submitted and accepted where required.
Distribution context
Consider how the application reached the Mac and what quarantine or Gatekeeper assessment conditions apply.
Why macOS may say an application is damaged
The word “damaged” does not necessarily mean the physical file is broken. The message can accompany bundle integrity, signature, quarantine, packaging, or Gatekeeper assessment problems.
Bundle changed
Verify whether files or nested components were modified after signing.
Download or packaging
Check whether the application was transferred or packaged correctly and whether the distributed artifact matches the tested one.
Gatekeeper context
Assess the exact distributed application rather than relying on the visible launch message alone.
Use spctl to investigate Gatekeeper assessment
spctl is useful when the signature itself verifies but the application still fails a Gatekeeper assessment. Read the assessment result as evidence about the launch context instead of using it as a replacement for codesign verification.
Assess the app
Determine whether Gatekeeper accepts the application as an executable object in the current environment.
Use verbose output
Capture the assessment result and rejection reason instead of relying only on the Finder message.
Assess the final artifact
Run the test against the application that users actually receive, not an earlier local build.
Downloaded software can behave differently from locally built software
Gatekeeper operates in a distribution context. A downloaded application can carry quarantine metadata that affects assessment, while a locally built application may not have the same launch context.
Diagnostic principle: compare the exact distributed artifact and its launch context with the locally tested application. Do not present removal of security controls as the default troubleshooting step.
Why Gatekeeper accepts an app on one Mac but rejects it on another
Different macOS versions, trust state, application artifacts, quarantine state, security configuration, distribution paths, notarization state, or architectures can produce different results.
Compare the environment
- macOS version
- System security configuration
- Certificate and trust state
- Quarantine context
- Architecture
Compare the artifact
- Exact application build
- Code signature
- Nested code
- Entitlements
- Notarization state
Best comparison: collect codesign verification and spctl assessment output from both Macs, then compare the exact application artifact and launch context.
Developer ID, signing, notarization, and Gatekeeper
These mechanisms are related but distinct. A practical troubleshooting model is Developer ID → Code Signing → Notarization → Gatekeeper. The failure point determines the tool and evidence you should inspect.
Developer ID
Establishes the signing identity used for the relevant macOS distribution scenario.
Code signing
Signs the application and its relevant code components with the intended identity.
Notarization
Submits the final software to Apple's notarization service where required.
Gatekeeper
Assesses software in the context in which it is being launched.
macOS signing failures in CI/CD
CI signing failures often happen because the runner is not equivalent to the developer's Mac. For repeatable releases, automating code signing in CI/CD helps make identity provisioning and signing steps explicit. Compare identity provisioning, private-key access, Keychain configuration, build user, entitlements, nested code, notarization credentials, and the final artifact.
Signing inputs
- Signing identity
- Private key
- Certificate provisioning
- Keychain
Build output
- Entitlements
- Nested code
- Final bundle contents
- Post-signing processing
Distribution
- Notarization credentials
- Submitted artifact
- Packaging
- Gatekeeper test artifact
Works locally but fails in CI
macOS version
Compare the operating-system environment used for local and CI builds.
Xcode version
Compare the toolchain and signing configuration used by both environments.
Signing identity and private key
Confirm the same intended identity is available and usable.
Keychain access
Check the build user's access to the signing key and relevant Keychain configuration.
Entitlements and provisioning
Compare the signed configuration and capabilities.
Bundle contents
Confirm CI did not add, remove, replace, or modify nested code after signing.
Notarization credentials
Check the credentials and submission result used by the CI workflow.
Final artifact
Verify and test the exact application produced for distribution.
The app signs successfully, but Gatekeeper rejects the distributed application
Assume MyApp.app passes the signing step on the build Mac, but the distributed copy fails to launch on another Mac.
The correct response is to trace the release through signing, bundle integrity, notarization, and Gatekeeper rather than simply signing the application again.
- Verify the signature.
- Inspect nested code.
- Inspect signed entitlements.
- Confirm the distributed artifact was not modified.
- Check notarization status.
- Run Gatekeeper assessment with
spctl. - Determine whether the failure is signature, notarization, quarantine, or another Gatekeeper condition.
- Fix the specific layer.
- Rebuild, sign, and notarize the final artifact where required.
- Test the exact distributed artifact.
Quick reference for common macOS signing and Gatekeeper symptoms
| Symptom | Likely layer | First check |
|---|---|---|
| No identity found | Certificate / key | Signing identities and corresponding private keys in the active Keychain. |
errSecInternalComponent | Keychain / key | Private-key access, Keychain permissions, user account, and signing environment. |
| Code object not signed | Signing | The named nested executable or other code component. |
| Sealed resource missing or invalid | Bundle integrity | Files changed, added, or removed after signing. |
| Code signature invalid | Signature | Bundle contents, nested code, and post-signing modifications. |
| Entitlement mismatch | Entitlements | Signed entitlements versus intended application capabilities. |
| Notarization rejected | Notarization | Apple's current submission result for the exact artifact. |
| Developer cannot be verified | Gatekeeper / trust | Signature, notarization, distribution source, and assessment context. |
| App appears damaged | Integrity / Gatekeeper | Signature, bundle contents, download integrity, and Gatekeeper assessment. |
spctl rejects app | Gatekeeper | Verbose assessment output and the exact distributed artifact. |
Prevent common macOS signing failures before distribution
Bundle discipline
- Sign the final application bundle.
- Sign nested code correctly.
- Do not modify the bundle after signing.
- Verify the final artifact.
Identity discipline
- Keep signing identities secure.
- Protect private keys.
- Inspect entitlements.
- Monitor certificate expiration and revocation.
Distribution discipline
- Notarize the final artifact where required.
- Test Gatekeeper assessment.
- Test the distributed artifact.
- Protect CI/CD signing credentials.
Frequently asked macOS signing questions
Why does codesign fail with errSecInternalComponent?
Check the private key, Keychain access, signing identity, permissions, build-user context, and any hardware or cloud signing configuration. The certificate can be present even when the private key cannot be used.
Why does codesign --verify fail?
Inspect bundle integrity, nested code, resources, requirements, entitlements, and post-signing changes. Use verbose verification to identify the component or property that failed.
Why does my Mac app say the developer cannot be verified?
Investigate the signing identity, signature, notarization state where applicable, Gatekeeper assessment, distribution method, and quarantine context. The message is not by itself proof that the signature is invalid.
Why does Gatekeeper say the application is damaged?
Possible causes include bundle modification, invalid signature, quarantine-related behavior, incomplete download, incorrect packaging, or Gatekeeper assessment failure. Verify the exact distributed artifact.
Why does an app sign successfully but fail Gatekeeper?
Signing and Gatekeeper are separate layers. Check the final bundle, nested code, entitlements, notarization, quarantine, distribution context, and spctl assessment.
What is the difference between codesign and spctl?
codesign is used to inspect and verify code signatures and related signing information. spctl is used to assess software in the context of macOS security assessment, including Gatekeeper behavior.
Does a valid code signature mean Gatekeeper will accept an app?
No. A valid signature is one part of the macOS software security path. Notarization, quarantine, distribution context, and Gatekeeper assessment can introduce additional conditions.
Why does notarization fail after signing succeeds?
Review the exact notarization submission result and final artifact. The application can be correctly signed while still failing Apple's notarization checks because of bundle contents, nested code, entitlements, packaging, or other current requirements.
Why does my app work locally but fail after download?
Compare the exact artifact, notarization state, distribution path, quarantine context, macOS environment, and Gatekeeper assessment. A local build does not necessarily have the same launch context as a downloaded application.
Why does macOS reject an app that has a valid Apple certificate?
A valid certificate does not by itself establish that the final application bundle, nested signatures, entitlements, notarization state, and Gatekeeper assessment are all acceptable.
Continue with the right macOS signing guide
Keep these resources distinct so each page answers a specific search intent rather than repeating the same macOS signing overview.
Identify the macOS layer that actually failed
Start with the signature, follow the bundle through identity and entitlements, then separate notarization and Gatekeeper from the signing process. That gives each error a specific place to investigate.
Explore macOS Code SigningChoose a signing setup that fits your macOS release process
If recurring key access or build environment differences are causing failures, compare protected signing options before changing certificates or weakening Gatekeeper controls.
Explore Cloud Code Signing