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.