I ran into this series of problems today:
0 dkg@alice:~$ export GNUPGHOME=$(mktemp -d) 0 dkg@alice:~$ echo 'pinentry-command /usr/bin/pinentry' > "$GNUPGHOME/gpg-agent.conf" 0 dkg@alice:~$ gpgconf --launch gpg-agent gpgconf: Configuration file of component gpg-agent is broken gpgconf: Note: Use the command "gpgconf --check-options gpg-agent" to get details. 1 dkg@alice:~$ gpgconf --check-options gpg-agent gpg-agent:Private Keys:/usr/bin/gpg-agent:1:0: 0 dkg@alice:~$
The user error in the above sequence of actions is, of course, that the configuration name is supposed to be pinentry-program and not pinentry-command. But GnuPG's debugging recommendation fails to provide useful help. The colon-delimited output is likely a mystery for most people, but even those who understand it are left no more enlightened about the nature of the reported problem.
Either gpgconf --check-options needs to be improved, or gpgconf --launch needs to give a better diagnostic recommendations, or gpg-agent needs to be more tolerant of misconfiguration, or somehow more verbose about the problems that it encounters.