Most migration failures are not random. The same five problems account for the vast majority of stalled or incomplete migrations. Here's how to diagnose and fix each one.
1. Graph API throttling (HTTP 429)
Microsoft Graph API enforces per-tenant rate limits. Hitting them produces a 429 Too Many Requests response with a Retry-After header. The fix is to respect the Retry-After value and use exponential backoff. Do not simply retry immediately — that makes throttling worse.
If throttling is persistent, reduce concurrency. Running 20 parallel mailbox migrations against a small tenant will throttle heavily. Dropping to 5–8 concurrent jobs usually resolves it.
2. Token expiry mid-migration
If you're using delegated permissions (a signed-in user's token), it expires after 60–90 minutes. Migrations that run longer than that will start failing silently. The fix is to use application permissions with a client credential flow — these tokens are renewed automatically and don't expire mid-run.
If your migration tool asks for a username and password to log in to Microsoft, it's using delegated auth. This will always fail for long-running migrations.
3. Missing admin consent
Application permissions require explicit admin consent before any API call succeeds. The symptom is a 403 Forbidden error on every request. Go to the app registration in Azure portal → API permissions and verify "Grant admin consent" has been clicked and shows a green tick next to every permission.
4. Large items exceeding the API limit
Emails with large attachments (>35 MB) and SharePoint files over 250 MB hit API limits. The symptoms are single-item errors in the log while everything else migrates fine. For email, the MIME size must be under the Graph API limit. For SharePoint and OneDrive files, use the resumable upload session API for anything over 4 MB. Most migration tools handle this automatically — if yours doesn't, it's a tool limitation.
5. UPN mismatch breaking mailbox mapping
If a user's email address in the source tenant doesn't match their UPN in the destination (e.g. [email protected] → [email protected]), the migration tool has no way to automatically match them. The symptom is mailboxes that show as migrated but the user can't find their email in the destination.
The fix is explicit user mapping — providing a CSV or configuration that maps each source address to its destination address before the migration starts. A good migration tool lets you review and override auto-mapped users before launch.
Always run a mapping review step before launching. If more than 5% of users are unmatched, stop and fix the mapping before starting — you cannot easily undo a partially-completed migration.