Google Workspace Migration: The Technical Gotchas Nobody Warns You About

A while back I got handed what my manager described as a "quick" project: move us off Google Workspace onto Microsoft 365. A few hundred users. "Just the email, really." I nodded, estimated a weekend, and was wrong about almost every part of that sentence.

If you've done a cloud email migration before, you already know where this is going. If you haven't, this post is the set of notes I wish someone had handed me on day one — the specific technical things that turn a "quick" migration into a multi-week project with a very tense cutover night. None of it is exotic. It's just the stuff that the marketing pages skip and you only discover once you're elbow-deep in it.

First mental model shift: it's not one migration

The single biggest reframe is this: "migrate off Google Workspace" is not one task, it's a bundle of loosely related ones, and each is a different technical problem with different tooling.

At minimum you're looking at:

• Mail — Gmail messages, with labels, threads, and folder structure
• Calendars — including recurring events and reminders, which serialize differently across platforms
• Contacts and tasks
• Drive and Shared Drives — files, folder trees, sharing permissions, version history
• Google Vault — compliance/archive data, if you use it
• Google Chat / Spaces — years of team conversation history
• Groups — which map (imperfectly) to Microsoft 365 Groups

Here's the trap: most tools do some of these well and silently ignore the rest. A tool that moves Gmail beautifully may not touch Drive. A tool that's brilliant at Drive-to-SharePoint won't go near a mailbox. I've watched a project discover mid-cutover that its chosen tool didn't handle Shared Drive permissions — which is a genuinely bad time to find out.

So before you evaluate a single tool, audit your actual workloads. Write down what you have, including the awkward stuff — suspended accounts, Shared Drives nobody owns anymore, Vault archives, Chat history, service accounts. That list is your real spec. (When I got to the "which tool" stage, this comparison of Google Workspace migration software saved me a lot of time, because it maps each tool to which workloads it actually supports per the vendor docs rather than the landing page — the mailbox-vs-files distinction in particular is where most planning goes wrong.)

Now, the gotchas.

Gotcha 1: authentication is not "enter a password"

If your mental model of migration auth is "give the tool an admin username and password," update it. That approach is both dead and dangerous in 2026.

On the Google side, the correct pattern is a service account with domain-wide delegation. You create a service account, authorize it in the Google Admin console, and grant it a specific set of OAuth scopes. That lets it impersonate users and read their mailboxes through the API — without anyone handing over individual credentials. Conceptually you're authorizing something like:

# OAuth scopes a migration service account typically needs (read access)
https://mail.google.com/                                  # Gmail
https://www.googleapis.com/auth/calendar.readonly         # Calendars
https://www.googleapis.com/auth/contacts.readonly         # Contacts
https://www.googleapis.com/auth/drive.readonly            # Drive (if in scope)

The scopes matter. Grant too few and the migration silently skips data; grant broad ones and your security reviewer will (rightly) ask why. Get the scope list nailed down before the migration weekend, not during it.

On the Microsoft 365 side, you authenticate with OAuth 2.0 modern auth. Basic authentication for Exchange Online is gone — Microsoft fully deprecated it — so any tool still offering a "use basic auth" fallback is a red flag on two counts: it's a security risk, and it will simply stop working. This is one area worth being strict about when you evaluate tooling: OAuth 2.0 only, no legacy fallback.

The practical takeaway: the auth setup is a real chunk of the project, it involves both admin consoles, and it's the first place a migration silently loses data if you get the scopes wrong.

Gotcha 2: Gmail labels don't map cleanly to Outlook folders

This one is subtle and it bites everyone.

Gmail uses labels. A single message can carry several of them — Clients, Invoices, and Q3 all at once. Outlook and Exchange use folders, and a message lives in exactly one. So when your migration tool hits a message with three labels, it has to make a decision, and the decisions are all imperfect:

Gmail (labels, many-to-one):
  message_1234  ->  [Clients, Invoices, Q3]

Outlook (folders, one-to-one) — the tool must choose:
  (a) duplicate the message into \Clients, \Invoices, and \Q3   → 3 copies
  (b) put it in one folder, drop the other associations         → lost structure
  (c) flatten to a single \Clients\Invoices\Q3 style path       → tool-dependent

There's no universally "correct" answer — it depends how your org uses labels. What matters is that a good tool lets you control this behavior, and a naive one just picks for you and hands you either a mailbox full of duplicates or a mailbox that's lost its organization. When you're testing tools, send yourself a few multi-labelled messages and see what actually lands on the other side. It's a five-minute test that reveals a lot.

Gotcha 3: the Microsoft Graph API will throttle you

You'd think the bottleneck in a migration is your internet connection. It isn't — it's Microsoft. The Graph API (and historically EWS) enforces throttling limits on how fast you can write into a tenant, and if you naively fire off parallel requests as fast as you can, you get rate-limited into a crawl or outright blocked.

Microsoft's own guidance on this is worth a read if you're building anything against Graph, not just for migrations:

Microsoft Graph throttling guidance - Microsoft Graph | Microsoft Learn

Learn the best practices to avoid throttling and maintaining optimal performance should your app be throttled.

learn.microsoft.com

When you hit the limit, the API returns 429 Too Many Requests, usually with a Retry-After header telling you how long to wait. The correct behavior is to respect it and back off:

# The pattern any competent migration engine implements internally
import time

def with_backoff(request_fn, max_retries=6):
    delay = 2
    for attempt in range(max_retries):
        resp = request_fn()
        if resp.status_code != 429:
            return resp
        # honor the server's guidance if present, else exponential backoff
        wait = int(resp.headers.get("Retry-After", delay))
        time.sleep(wait)
        delay = min(delay * 2, 60)
    raise RuntimeError("Throttled past max retries")

You almost certainly won't write this yourself — but you should know that it's what separates a migration tool that finishes on a 2,000-mailbox tenant from one that stalls at 3 a.m. When a vendor talks about "automatic throttle management," this is what they mean, and it's worth more than any headline "migrates X GB/hour" number, because raw speed is meaningless the moment Microsoft starts saying 429.

Gotcha 4: never do a big-bang cutover — use delta sync

The scariest way to run a migration is the obvious one: pick a Friday night, copy everything, flip DNS, pray. The problem is time. If copying takes twelve hours, that's twelve hours where new mail is arriving in Google that your copy doesn't have. Anything that lands mid-migration is at risk.

The pattern that fixes this is incremental (delta) migration:

1. Start copying days or weeks ahead, while everyone keeps working normally in Google Workspace.
2. The tool moves the bulk of the data in the background.
3. At cutover, it runs a final pass that transfers only what's new or changed since the last sync — usually a few hours of mail, not years of it.
4. You flip the MX record, and downtime is measured in minutes.

The critical detail to verify: the final pass must be a true incremental sync, not a full re-run, and it must not create duplicates. This is a capability question to put to any tool directly — "does your delta pass deduplicate against what's already migrated?" — because the ones without proper delta support turn every re-run into a mess.

Gotcha 5: Drive is a completely different project

If Google Drive is in scope, mentally file it as a separate project with its own budget and timeline, because the mail-vs-files split is the biggest planning mistake in this whole category.

Three specific landmines:

• Permissions don't map. Google's sharing model and SharePoint's permission model are genuinely different shapes. A clean lift-and-shift will mangle who-can-see-what unless the tool does real permission mapping. Pre-migration reporting that flags permission conflicts before anything moves is the feature you want here.
• Docs conversion is imperfect. Google Docs, Sheets, and Slides get converted to Office formats. It's usually fine, but complex formatting and anything with embedded scripts can drift. Test on a representative sample — don't assume.
• Vault is usually skipped entirely. If you hold compliance archive data in Google Vault, most tools won't touch it, and "migrate to a Microsoft 365 archive mailbox" is a different thing that people constantly confuse with "migrate Vault data." If Vault matters, confirm it explicitly in the vendor's own docs.

The upshot: mailbox migration and file migration are different capabilities. Plenty of teams deliberately pair two specialist tools — one for mail, one for files — and get a better result than one tool that does both adequately. Decide which approach you're taking during planning, not halfway through.

A pre-migration checklist I'd actually use

If you take nothing else from this, take the order of operations:

[ ] Inventory every workload (mail, Drive, Shared Drives, Vault, Chat, Groups, contacts, tasks)
[ ] Include the messy stuff: suspended accounts, orphaned Shared Drives, service accounts
[ ] Decide: one broad tool, or two specialists (mail + files)?
[ ] Confirm each needed workload in the vendor's DOCS, not the landing page
[ ] Lock down OAuth scopes (Google) + confirm OAuth 2.0-only (Microsoft)
[ ] Verify true delta sync with deduplication
[ ] Verify automatic Graph API throttle handling
[ ] Run a real-data test migration on a handful of live mailboxes
[ ] Test the awkward cases: multi-labelled Gmail, shared/permissioned Drive files
[ ] Plan the MX / DNS cutover and a rollback window
[ ] Only then: buy, and schedule the cutover

That "confirm in the docs, not the landing page" line is the one that saves projects. Vendor marketing routinely overstates workload coverage, and the gap is always discovered at the worst possible moment.

Wrapping up

A Google Workspace migration is very doable — I've done several since that first "quick weekend" — but the difficulty is never where you expect. It's not the volume of data; it's the auth setup, the label-to-folder impedance mismatch, the API throttling, the discipline of a proper delta cutover, and the quiet reality that Drive is its own beast.

Get the workload audit right, be strict about OAuth and delta support, and test on your real data before you commit a cent, and the actual cutover becomes the calm, boring event it should be. If you're at the tool-selection stage and want the workload-by-workload breakdown rather than repeating my trial-and-error, the Google Workspace migration software comparison I mentioned earlier lays out which tools genuinely cover which workloads — start there with your inventory in hand.

Have you run one of these? I'm curious what bit you that isn't on my list — the comments are open.