Fixing TLS Handshake Failures in IMAP Migrations

The migration log shows STARTTLS handshake failed or TLS handshake error: unsupported protocol and the job never even sends an IMAP LOGIN. That's because TLS fails before IMAP commands run — the secure tunnel never gets built, so the protocol on top of it never starts. The good news: TLS errors are deterministic. The handshake either completes or it doesn't, and the cause is almost always one of four things. This post walks through each, in the order you should rule them out.

What you'll see in the log#

The exact wording depends on which TLS library the migration tool links against, but the patterns are recognizable:

• STARTTLS handshake failed
• TLS handshake timeout
• ssl3_get_record:wrong version number
• unable to get local issuer certificate
• tls: server selected unsupported protocol version 301
• certificate has expired or certificate not yet valid
• tlsv1 alert protocol version

Any of those means the IMAP layer never started. The cause is below IMAP, in TLS or in the network path.

The four causes, in priority order#

1. Destination disabled TLS 1.0 / 1.1, source still defaults to it#

Modern destinations — Microsoft 365, Google Workspace, most hosted providers — accept only TLS 1.2 and TLS 1.3. Older self-hosted source servers still negotiate TLS 1.0 by default, and a migration tool that links a recent OpenSSL build will refuse to talk to them. The error reads tlsv1 alert protocol version or unsupported protocol.

The fix is to upgrade TLS on the source, not to weaken the migration host. Most modern IMAP servers (Dovecot, Cyrus, Courier) support TLS 1.2 with a one-line config change. If the source genuinely cannot be upgraded — a legacy appliance, an end-of-life system — you can temporarily enable TLS 1.0 on the migration host for that source only, but treat it as a last resort and remove it after cutover.

2. Corporate proxy MITMing the IMAP connection#

Many enterprise networks run TLS inspection on egress traffic. The proxy terminates the original TLS session, opens a new one to the real server, and re-signs the cert with the corporate CA. For HTTPS this usually works because your OS already trusts the corporate CA. For IMAP, the migration tool may use a different trust store and reject the substitute cert.

Two giveaways:

• openssl s_client -connect imap.gmail.com:993 shows a cert whose subject is CN=corporate-proxy-ca instead of CN=imap.gmail.com.
• The same migration works fine from a home network or a cloud host outside the corporate egress.

The cleanest fix is to ask the network team to add an IMAP bypass — exclude port 993 to known IMAP destinations from TLS inspection. Otherwise, install the corporate root CA into the migration host's trust store so it accepts the re-signed certs.

3. Incomplete certificate chain on the source#

The IMAP server is supposed to send its full chain — leaf, intermediate, and any cross-signs — during the handshake. Some servers send only the leaf, relying on the client to fetch intermediates. Browsers do this automatically. Most TLS libraries used by migration tools do not.

Run openssl s_client -connect imap.source.example.com:993 -showcerts. If you see one BEGIN CERTIFICATE block and the verification line says unable to get local issuer certificate, the chain is incomplete. Fix it server-side by installing the intermediate alongside the leaf.

4. Outdated cipher suites at the source#

Even with TLS 1.2 negotiated, the two sides have to agree on a cipher suite. Source servers stuck on RC4 or 3DES will fail against any modern client. The error reads no shared cipher or handshake failure.

Same fix as protocol version: add modern ciphers to the source. Anything in the ECDHE-RSA-AES128-GCM-SHA256 family works for every modern destination.

The 5-minute diagnostic with openssl#

1. Confirm a basic TLS connection

   From the migration host, run openssl s_client -connect imap.source.example.com:993. If it completes and shows a cert, TLS itself works. If it errors, capture the exact line and continue.

2. Pin the protocol version

   Re-run with -tls1_2 and then -tls1_3. If only one of the two works, the server supports a narrower range than the migration tool defaults to. Note which version connected.

3. Inspect the certificate chain

   Add -showcerts to the command. Count the BEGIN CERTIFICATE blocks. A complete chain has the leaf plus at least one intermediate. Single-cert output means the server is not sending the chain.

4. Check the cert subject

   Look at the subject= line in the openssl output. If it doesn't match the IMAP server's domain — or if it matches your corporate proxy — TLS inspection is in play.

5. Run the same test from outside the network

   From a laptop on a phone hotspot or a cloud VM, repeat step 1. If it works there but fails from the migration host, the cause is on your network, not the server.

For background on the IMAP commands that follow the TLS handshake — and on how STARTTLS differs from implicit TLS on port 993 — the IMAP protocol glossary covers the protocol layer in detail.

Settings that help on the migration host#

Mailbox Taxi defaults are conservative — TLS 1.2 minimum, modern cipher suites, full chain validation. For a problematic source you can override per-connection:

• Minimum protocol version: drop to TLS 1.0 only for that source. Other migrations on the same host are unaffected.
• Cipher list: append legacy ciphers for a single source. Removed automatically after the cutover.
• CA bundle: point at a custom bundle that includes your corporate root, so MITM proxies validate cleanly.

All three live in the per-connection advanced settings, not the global config. Treat per-source overrides as temporary and document them in your runbook so you remove them after the migration completes.

When TLS isn't really the problem#

Two errors look like TLS failures but aren't:

• Connection reset during the handshake. The handshake never completed because the connection itself was killed. See the connection reset troubleshooter for the firewall and NAT cases.
• Handshake timeout with no TLS alert. A packet got dropped or the server is too slow to respond. Almost always a network path issue, not a TLS configuration issue.

If you've ruled both out and the handshake still fails, you have a genuine TLS mismatch. For the broader run-book of migration errors by symptom, the troubleshooting hub groups them. For end-to-end procedure including TLS verification as a pre-flight step, the IMAP migration guide and the complete email migration guide both include checklist items for this.