Troubleshooting
Debug logging
Set SCDAEMON_SE_DEBUG to any value to enable verbose logging of every Assuan line to stderr (payloads are redacted — see Architecture § Request flow).
Since gpg-agent runs scdaemon-se directly (no shell), you need a wrapper script to both set the variable and capture stderr to a file. One is already provided at scripts/scdaemon-se-wrapper.sh — it sets SCDAEMON_SE_DEBUG=1 and logs to ~/.local/share/scdaemon-se/debug-<YYYYMMDD>.log, creating the directory 0700 and the log file 0600 so it isn’t readable by other users on the machine. Point gpg-agent.conf at it:
scdaemon-program /path/to/scdaemon-se-wrapper.sh
Then restart gpg-agent (gpgconf --kill gpg-agent) and tail the log:
tail -f ~/.local/share/scdaemon-se/debug-$(date +%Y%m%d).log
This is a different wrapper from the one ./scripts/setup.sh generates — that one just execs the binary with no logging at all. If you used setup.sh and want logging, either edit its generated wrapper or point gpg-agent.conf at scripts/scdaemon-se-wrapper.sh instead.
Common errors
“Secure Enclave is not available on this device” — you’re on hardware without a Secure Enclave (pre-2018 Mac without a T2 chip, or an Intel Mac without T2), or running in a virtual machine (VMs don’t expose the Secure Enclave).
“gpg: selecting card failed: No such device” — check gpg-agent.conf’s scdaemon-program path is correct and executable, then gpgconf --kill gpg-agent.
“gpg: signing failed: No secret key” — shadow stubs are probably missing: gpg-connect-agent "LEARN --sendinfo --force" /bye. Or the public key was never imported — see Key Management § Exporting the public key.
“gpg: decryption failed: No secret key” — same causes as above, but also confirm the decryption subkey is actually in your keyring (it’s not created by default — see Security Model).
Socket path too long — GnuPG limits Unix socket path length (typically 104 characters). If $GNUPGHOME is very long, use a shorter one:
export GNUPGHOME=/tmp/gnupg
mkdir -p "$GNUPGHOME"
chmod 700 "$GNUPGHOME"
Keychain access prompts — macOS asking permission for scdaemon-se to read its stored key handles. Click “Always Allow” to suppress future prompts for the same operation. Note that reading a key’s existence (as --inspect/scdaemon-se-inspect’s card/slot summary does) never prompts; reading a key’s stored secret data (as the raw registry/metadata JSON sections of scdaemon-se-inspect do) can. See CLI Reference for the exact distinction.
Checking Secure Enclave availability
scdaemon-se --inspect
If this runs without error (regardless of whether keys already exist), the binary at least started and could check SecureEnclave.isAvailable — the daemon exits at startup if it can’t.