This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.

Why doesn't Dovecot work?

It says password mismatch

If you're using PAM:

For non-PAM set auth_debug_passwords=yes and look at what it says in the logs. If it's trying to use a wrong password scheme, you can change that. See ["Authentication/PasswordSchemes"]

It says Can't load certificate

If the key isn't password protected and you get an error like:

Sep 29 01:33:54 mail dovecot: imap-login: Can't load certificate file /etc/ssl/private/ssl-cert-mail-cacert.pem: error:0906D06C:PEM routines:PEM_read_bio:no start line
Sep 29 01:33:54 mail dovecot: child 27252 (login) returned error 89
Sep 29 01:33:54 mail dovecot: imap-login: Can't load certificate file /etc/ssl/private/ssl-cert-mail-cacert.pem: error:0906D06C:PEM routines:PEM_read_bio:no start line
Sep 29 01:33:54 mail dovecot: child 27253 (login) returned error 89

You may have mixed up the ssl_cert_file and ssl_key_file settings in the config file. (v1.1.4+ mentions this in the error message.)

User's IMAP connection gets unexpectedly closed while retrieving headers of a large folder

And the log looks like:

Sep 12 16:10:34 hostname dovecot: IMAP(username): block_alloc(): Out of memory
Sep 12 16:10:34 hostname dovecot: child 17717 (imap) returned error 83 (Out of memory)

You may need to increase the mail_process_size setting in the config file. (v1.1.4+ mentions this setting in the latter error message.)