Code Signing Troubleshooting by Platform
Code signing failures do not look the same across Windows, Java, macOS, and PowerShell. The tools, signature formats, trust models, certificate stores, and verification steps change with the platform.
Choose the Troubleshooting Path
These guides form a focused troubleshooting cluster. Each page starts from the failure users actually see and works backward to the relevant signing, certificate, trust, integrity, policy, or environment layer.
Windows Signing Problems
Use this guide when Windows software cannot be signed, verified, trusted, or distributed as expected. It covers certificate selection, private keys, SignTool, certificate chains, SmartScreen, timestamps, HSM and cloud signing, and CI/CD issues.
Windows signing problemsAuthenticode Errors
Use this path for broader Authenticode signature and verification failures across supported Windows artifacts. It focuses on how the signature, certificate, chain, timestamp, and file integrity interact during verification.
Authenticode errorsJAR & Java Signature Errors
Use this guide for Java archive signing and verification failures involving jarsigner, keytool, keystores, aliases, certificate chains, timestamps, digest failures, invalid signatures, and Java trust.
codesign & Gatekeeper Errors
Use this guide when a macOS application fails signing, verification, notarization, or Gatekeeper assessment. It separates code signature problems from entitlements, certificate trust, quarantine, notarization, and Gatekeeper conditions.
macOS Gatekeeper errorsScript-Signing Errors
Use this guide when a PowerShell or Authenticode-signed script will not sign, verify, or execute. It separates signature status from certificate trust, timestamps, execution policy, file-origin metadata, and CI/CD environment problems.
Script-signing errorsNot sure which guide you need?
Match the failure to the tool or runtime named in the error. signtool points toward Windows signing, jarsigner toward Java, codesign toward macOS, and PowerShell's Authenticode commands toward script signing.
Need help resolving a signing failure?
If signing or verification is blocking a release, discuss the issue with the Code Signing Solution team and identify the next practical step.
Contact the Code Signing Solution teamThe Common Diagnostic Model
Although every platform implements signing differently, most troubleshooting can be narrowed by asking the same high-level questions. The platform guide then supplies the commands and rules specific to that environment.
Which Layer Is Failing?
Use the symptom as the entry point, but confirm it with the platform's verification tools. This avoids applying certificate fixes to problems that are actually caused by file modification, trust, policy, or distribution.
| Observed problem | Likely layer | Best starting point |
|---|---|---|
| Signing command cannot access the identity | Certificate / private key | Inspect the signing identity and key access in the relevant platform store or provider. |
| Signature fails after packaging | Artifact integrity | Compare the final distributed artifact with the artifact that was signed. |
| Signature is valid but signer is not trusted | Certificate chain / trust | Inspect signer, intermediate certificates, root trust, and local policy. |
| Timestamp operation fails | Timestamp | Check TSA configuration, connectivity, response, and timestamp certificate trust. |
| Software signs but will not run | Platform policy / distribution | Use the platform's runtime assessment tool rather than repeatedly re-signing. |
| Works locally but fails in CI/CD | Environment | Compare identity, key access, account, trust store, toolchain, policy, and final artifact. |
Choose a code signing certificate for your platform
Once the signing problem is understood, compare code signing certificate options for your software, platform, and signing environment.
Explore Code Signing CertificatesDo Not Mix Platform Fixes
Code signing is a shared security concept, but the implementation is platform-specific. Windows Authenticode, Java JAR signing, macOS code signing, PowerShell script signing do not use identical file structures, commands, trust decisions, or distribution controls.
A troubleshooting step that makes sense on one platform can be irrelevant or actively misleading on another. For a Windows-specific workflow, the Windows code signing process provides the platform context; always start with the tool, artifact type, and runtime named in the failure.
Identify the platform from the failure
- SignTool / SmartScreen: open Windows signing troubleshooting.
- Authenticode: open the broader Authenticode errors guide.
- jarsigner / keytool: open the JAR and Java errors guide.
- codesign / spctl / Gatekeeper: open the macOS guide.
- Get-AuthenticodeSignature / Set-AuthenticodeSignature: open the script-signing guide.
Platform Troubleshooting Resources
Windows signing problems
Certificate, key, SignTool, trust, SmartScreen, timestamp, HSM, cloud signing, and CI/CD troubleshooting.
Authenticode errors
Signature structure, verification, integrity, certificate chain, timestamp, and Authenticode-specific failures.
JAR & Java Signature Errors
JAR signing and verification failures, keystores, aliases, digests, certificate chains, timestamps, and trust.
codesign & Gatekeeper errors
Signing, nested code, entitlements, notarization, quarantine, Gatekeeper assessment, and CI failures.
Script-signing errors
Authenticode script signatures, certificate trust, HashMismatch, execution policy, RemoteSigned, AllSigned, and CI/CD.
Prepare software for distribution
For teams preparing a release, review code signing options intended for software distribution and build a consistent signing process.
Code signing for software distribution