Email Migration Troubleshooting: The Complete Reference

A migration that finishes cleanly is forgettable. A migration that fails at 2am, throwing errors you've never seen, against a provider whose docs are 18 months out of date — that's the one you'll remember. This reference is the diagnostic map: how to categorise the failure, what to check first, which tools tell you the truth about the wire, and how to retry without making it worse. Skim it now; you'll come back to it under pressure.

Categorising the failure before you touch anything#

The single biggest mistake during a stalled migration is changing things before you know what broke. Stop. Categorise. Then act.

Almost every migration failure falls into one of six categories:

1. Authentication. The tool can't prove who it claims to be to the source or destination provider.
2. Throttling. The provider is rate-limiting your tool. The connection is fine; the volume is the problem.
3. Permissions. You're authenticated but not authorized to read/write what you're trying to.
4. Data integrity. Items are being copied but not faithfully — duplicates, missing folders, corrupted bodies, encoding errors.
5. Network. Something between your tool and the provider isn't behaving — TLS handshake, DNS, MTU, proxy.
6. DNS / cutover. Specific to the post-cutover phase: mail going to the wrong place, autodiscover failing, MX records not propagating.

Knowing the category narrows the next question from "what do I do" to "which of three things do I check." That's the difference between a 20-minute fix and a 4-hour panic.

The diagnostic order#

Always work from the outside in. The order matters because each step rules out a layer before you spend time on the next.

Step 1: Did authentication actually succeed?#

Before anything else, confirm both source and destination authenticated successfully and that the tokens are still valid.

For OAuth-based connections:

• Has the refresh token expired or been revoked?
• Has the user changed their password (which can invalidate refresh tokens)?
• Has admin consent been revoked at the tenant?
• Has the OAuth app's secret rotated or expired?

For app-password / basic auth connections:

• Is the app password still valid? Gmail and Yahoo app passwords are revoked when 2FA is reconfigured.
• Did the user change their primary password?
• Did the provider deprecate basic auth on this account?

For Modern Auth / Microsoft 365:

• Is the migration app registered with the right Graph or EWS permissions?
• Has Conditional Access blocked the connection?
• Is the account in a state (locked, MFA-pending) that prevents non-interactive auth?

Common error messages in this category:

• AUTHENTICATIONFAILED — IMAP auth rejected.
• OAuth2 token expired — refresh path needs to run.
• LOGIN failed: [AUTHENTICATIONFAILED] Invalid credentials — typically basic auth being rejected.
• Modern authentication is required — basic auth disabled by tenant policy.

If auth is broken, nothing else works. Fix auth first. The fix authentication failed post walks the specific recovery sequences per provider.

Step 2: Can you LIST?#

If auth succeeded, the next check is whether you can list folders/labels on both source and destination.

A successful LIST tells you:

• The connection is open.
• Your credentials have at least read access at the mailbox scope.
• Folder enumeration is working (no UTF-7 issues, no permission gaps).

A failed LIST after a successful auth is almost always permissions. The credential proved who you are; the authorization scope doesn't include what you're asking for.

For Microsoft Graph / EWS:

• Check the application permissions granted to the migration app.
• For impersonation models, check ApplicationImpersonation role assignment.
• For delegated permissions, confirm the user actually has the role you assumed.

For IMAP:

• Check whether the mailbox is delegated/shared and you're using the right access method.
• Confirm IMAP is enabled at both the user and tenant level.

Step 3: Is throttling active?#

If LIST works but item-level reads stall, you're probably hitting throttling.

Throttling signatures look like:

• Too many simultaneous connections (IMAP).
• IMAP BYE mid-session with a server message about overuse.
• HTTP 429 (Microsoft Graph, Google APIs).
• Variable, climbing latencies followed by intermittent disconnects.
• Errors that affect the whole batch, not individual mailboxes.

The diagnostic test: drop concurrency to one connection, wait 5 minutes, retry a single mailbox. If it succeeds, you were throttled. The fix IMAP throttling errors post has provider-specific backoff strategies; the fix Office 365 throttling post and fix too many IMAP connections cover the most common cases.

Step 4: Check the destination#

If reads from source are working and writes to destination are failing, you've narrowed the problem.

Common destination-side issues:

• Destination mailbox not provisioned, or in a transitional state.
• Destination tenant licensing not yet applied to the user.
• Destination throttling (Microsoft Graph and Exchange Online both throttle aggressively).
• Destination message size limit (default 35MB at Microsoft 365; some IMAP servers lower).
• Destination folder permissions misconfigured for shared/delegated mailboxes.

Common destination error messages:

• Message too large for destination — exceeds the destination's message size policy.
• Folder UTF-7 conversion error — folder name contains characters the destination IMAP can't represent.
• Insufficient privileges to complete the operation — Graph-level permission missing.

Step 5: Inspect the wire#

When the above hasn't isolated the issue, drop down a level. You're verifying whether the issue is your migration tool, the network, or the server.

For IMAPS, a manual conceptual test:

• Open a TLS connection to the IMAP server (using a tool like openssl s_client).
• Issue LOGIN, LIST, and SELECT commands manually.
• Observe how the server responds.

This isolates:

• Whether TLS negotiates at all (rules out STARTTLS handshake failed).
• Whether auth works outside your migration tool (rules out tool-specific issues).
• Whether the server's responses match what your tool reports it received.

You don't need to know the IMAP protocol deeply. You need to know whether you can do the same operations by hand. If yes, the tool is misbehaving. If no, the network or server is the problem.

For HTTPS APIs (Graph, Gmail API), the equivalent is a manual call with curl using the bearer token your tool obtained. Same principle: isolate the layer.

Provider error messages worth memorising#

Every engineer who runs more than a few migrations builds the same mental dictionary. A short version:

Microsoft 365 / Exchange Online#

• Modern authentication is required — basic auth disabled. Use OAuth.
• The user is not assigned to the application — Conditional Access or app assignment issue.
• MailboxStatisticsServiceUnavailableException — transient; retry after backoff.
• Quota exceeded — destination over its size limit.
• HTTP 429 with Retry-After header — Graph throttling. Respect the header value.

The fix modern auth required post covers the OAuth migration path for tenants where basic auth is off.

Gmail / Google Workspace#

• Web login required — Gmail blocked the IMAP login as suspicious. Allow access in security settings or use OAuth.
• Invalid credentials (after correct password) — usually app password issue or 2FA conflict.
• Lookup failed on an item — Gmail label-to-folder mapping issue.
• BYE Too many simultaneous connections from this IP — concurrency throttle (typically ~15 per account).

The fix Gmail app password post walks the credential side; fix OAuth token expired handles the OAuth path.

Generic IMAP#

• AUTHENTICATIONFAILED — credentials rejected.
• BAD Command unknown — server doesn't speak the dialect your tool used.
• NO Mailbox does not exist — folder name mismatch (often UTF-7 or system folder naming).
• STARTTLS handshake failed — TLS negotiation broken; may indicate cipher mismatch or interception.

MFA-related#

• MFA challenge required — interactive flow needed; your non-interactive tool can't proceed.
• Conditional Access blocked sign-in — policy excluded this app or location.

The fix MFA blocking migration post covers the patterns for getting migration tooling past MFA without weakening the user's security posture.

Data integrity issues#

These are the worst category because they surface late and can't always be cleanly undone.

Duplicate emails#

Symptoms: users report two copies of the same email after migration.

Causes:

• Re-running the migration without per-item dedup state.
• Concurrent migrations on the same mailbox.
• A retry after a write succeeded but the acknowledgement was lost.
• Message-ID rewriting by intermediate gateways.

Recovery: most tools include a dedup utility that runs on the destination. Confirm what the tool considers a duplicate (often Message-ID + folder + internal date) and verify on a sample before running it across the tenant. The fix duplicate emails after migration post has provider-specific recipes.

Missing folders#

Symptoms: users report a folder they had in source is missing in destination.

Causes:

• Folder mapping rules excluded it (system folders, custom rules).
• Non-ASCII characters in the folder name failed UTF-7 conversion.
• Source folder was a Gmail label rather than a folder, and label-to-folder mapping wasn't configured.
• Destination provider has reserved names that conflict with source folder names.

Recovery: check the migration report for the folder by name. Most of the time it's been mapped to a slightly different name. The fix missing folders after migration post covers the per-provider naming quirks.

Encoding / character set issues#

Symptoms: emails arrive but the subject line or body shows mojibake or question marks.

Causes:

• Source message encoded in a non-UTF-8 charset; tool didn't preserve original encoding declaration.
• Subject line MIME-encoded in a way the destination doesn't fully support.
• Tool converted to UTF-8 but stripped the original Content-Type declaration.

Recovery: usually requires re-fetching the affected items from source with the original encoding preserved. Sample first; verify the pattern; then plan the recovery batch.

Timestamp drift#

Symptoms: emails arrive in destination with wrong send/receive dates.

Causes:

• Tool used the system clock at write time rather than preserving the source Date: header.
• IMAP INTERNALDATE not preserved (this is the date the destination indexes for sort order).
• Timezone conversion errors.

Recovery: preserving INTERNALDATE is a tool-level capability. Confirm yours does it before the migration; you can't easily fix it after.

Network and DNS troubleshooting#

Network issues during migration are less common than the categories above, but they're often the slowest to diagnose because the symptoms look like throttling or auth.

TLS handshake failures#

• Mismatched cipher suites between client and server.
• Certificate chain validation failures (intermediate CA missing).
• TLS interception by a corporate proxy.
• Server requiring TLS 1.3 when client is configured for TLS 1.2 (or vice versa).

The fix TLS handshake failure post covers the specific diagnoses.

MTU and packet fragmentation#

Symptoms: large messages fail consistently; small messages succeed.

Cause: usually a network MTU mismatch causing fragmentation issues, often on VPN connections.

Fix: lower the MTU on the migration workstation's network interface, or run the migration on a non-VPN path.

DNS issues post-cutover#

After MX cutover, the most common issue is sender confusion. External senders' resolvers may have cached the old MX. Wait the TTL out before treating it as an issue. If senders are still hitting the old MX 72 hours after cutover with TTL set correctly, something downstream is caching incorrectly — check secondary DNS, downstream relays, and the sender's own infrastructure.

Safe retry strategies#

Once you've identified the failure category and addressed the cause, retrying is straightforward — if you do it right.

Retry by category#

• Auth failures. Safe to retry the affected mailboxes immediately after credentials are fixed. Per-item state is unchanged.
• Throttling. Wait at least 15–30 minutes. Lower concurrency by half. Retry. If it succeeds, you can slowly raise concurrency back; if it throttles again, leave concurrency low for the rest of the job.
• Permissions. Retry after the permission grant. Some providers cache permission lookups for several minutes; if you retry immediately and still fail, wait 10 minutes.
• Data integrity. Do not retry blindly. Investigate. Many integrity issues are made worse by retries.
• Network. Retry once the network issue is confirmed fixed. Verify by re-doing the wire-level test from Step 5.

Resume vs start-over#

Two questions decide:

1. Does your tool's resume model rely on per-item state (UID, Message-ID) or per-folder state?
2. Has the source mailbox changed since the failure?

Per-item state + unchanged source = safe resume. Per-folder state + any change = consider starting over for the affected mailboxes only.

If you start over for a mailbox, the destination must be cleared first or you'll have duplicates. Most tools include a "clear destination mailbox" mode; some require manual cleanup. Confirm before you start.

What to log during a retry#

Every retry should produce its own log entry, not overwrite the previous attempt. You want, after the migration:

• The original failure log.
• The cause analysis.
• The retry log showing what changed and what succeeded.

Auditors and users both ask the same question: what happened? The full retry trail answers it.

When to escalate#

You're not always the right person to fix the problem. Three escalation triggers:

• Pattern across multiple tenants. If the same error appears in unrelated tenants in the same window, you may be looking at a provider-side incident. Check service health dashboards before going deeper.
• Data integrity at scale. If more than 5% of items in a batch show integrity issues, stop the batch. Investigate before processing more.
• Cutover window pressure. If you're inside a cutover window and 50% gone with an unfamiliar error, call your senior engineer or vendor support before the window closes. The cost of a missed cutover is higher than the cost of a phone call.

The diagnostic order, one more time#

Under pressure, you'll forget the categories. The order, however, sticks:

1. Did auth succeed? Confirm both ends.
2. Can you LIST? Confirms scope and folder enumeration.
3. Is throttling active? Drop concurrency, retry once.
4. Check the destination. Permissions, quotas, message size.
5. Inspect the wire. Take the tool out of the loop.
6. Categorise and retry. By failure type, not by hope.

The complete email migration guide is the end-to-end playbook; this reference is the diagnostic side. Keep it open in another tab next time you're in a window. You'll get faster every job.