Introduction

gpg failed to sign data is a Git-side symptom, not the root cause. Git asked GPG to sign the commit or tag, and GPG could not complete the operation because of a missing key, a bad gpg-agent setup, a broken terminal configuration, or a mismatched Git config.

The fastest way to fix it is to test GPG outside Git first. Once plain GPG signing works, Git signing usually works too.

Diagnose the Real Failure

Start by checking whether your secret key is present and whether GPG can use it.

gpg --list-secret-keys --keyid-format LONG
echo "test" | gpg --clearsign

If the second command fails, the issue is in GPG itself, not in Git. Typical causes include:

• No secret key exists on this machine.
• The configured signing key is wrong.
• 'gpg-agent is not running correctly.'
• 'pinentry cannot open a prompt.'
• The terminal session does not expose GPG_TTY.

Next, inspect Git’s signing-related configuration.

git config --global --get user.signingkey
git config --global --get commit.gpgsign
git config --global --get gpg.program

If user.signingkey does not match one of the secret keys shown by GPG, Git is asking for the wrong key.

A Working Setup

A common minimal setup on macOS or Linux looks like this:

1git config --global user.name "Mark Qian"
2git config --global user.email "[email protected]"
3git config --global user.signingkey ABCD1234EF567890
4git config --global commit.gpgsign true
5git config --global gpg.program gpg
6
7echo 'export GPG_TTY=$(tty)' >> ~/.zshrc

Then restart the shell or reload the profile:

source ~/.zshrc
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

After that, test again:

git commit --allow-empty -m "test signed commit"

If the commit succeeds, the chain from Git to GPG to the agent is working.

Why GPG_TTY Matters

In terminal-based workflows, GPG often needs pinentry to ask for the private key passphrase. Without GPG_TTY=$(tty), the prompt may have nowhere valid to attach, so Git only reports a generic signing failure.

That is why the same key can appear valid when listed with gpg --list-secret-keys, but signing still fails inside a shell session. Listing keys does not require passphrase entry; signing does.

GUI environments can have similar issues if Git runs in one environment and GPG expects another. In that case, explicitly setting gpg.program and restarting gpg-agent is often necessary.

Expired or Unusable Keys

If the key exists but has expired, Git signing will still fail. Check the expiration date with:

gpg --list-secret-keys --keyid-format LONG

If needed, update the key:

gpg --edit-key ABCD1234EF567890

Then use the expire command inside the interactive prompt and save the changes.

Also confirm that the key has signing capability. Some keys are created with subkeys, and Git may need the signing subkey rather than the primary key ID depending on how your environment is configured.

Common Pitfalls

One common mistake is importing only the public key. Git signing requires the secret key. If gpg --list-keys shows the key but gpg --list-secret-keys does not, signing cannot work.

Another pitfall is mixing GPG versions or binaries. On some machines, Git points at a different GPG executable than the one you tested manually. Check git config --get gpg.program and which gpg.

Developers also often forget that IDEs may launch Git in a different environment from the terminal. A commit that signs correctly in Terminal can still fail in an editor-integrated Git client if the agent or pinentry is not available there.

Finally, do not debug only from Git’s top-level error message. Run GPG commands directly and inspect the lower-level failure.

Summary

• 'gpg failed to sign data usually means GPG, the agent, or Git config is misconfigured.'
• Verify plain GPG signing outside Git first.
• Make sure user.signingkey matches a real secret key.
• Set GPG_TTY=$(tty) in terminal workflows and restart gpg-agent.
• Check for expired keys, wrong binaries, and IDE-specific environment mismatches.