MIGRATION · April 24, 2026 · 12 min read

SharePoint migration checklist: what to audit before cutover

SharePoint migrations tend to fail the same way every year. Documents get moved before the content types are created, everything lands in the wrong list schema, and the whole project gets re-done over a weekend nobody wanted to work. This framework distills what works in practice, updated for 2026 now that Graph-API-driven migrations are standard and SPMT is reserved for the narrow cases where Graph genuinely cannot do the job.

The intended audience is IT leads running tenant-to-tenant, divestiture, or acquisition migrations on SharePoint Online. For SharePoint 2016 on-prem environments, the sequencing still applies, but the tooling story is different.

Pre-migration audit

Successful migrations start with an audit. Failed ones don’t. The audit answers three questions:

What is the site footprint? How many site collections? How many are active vs orphaned (no active users in 180 days)? How much content by size? Which sites host the top 20% of active documents? The answer to the last question shapes the cutover order.
What is the permission sprawl? How many Anyone-with-the-link sharing links exist? How many external guests have access? Which sites have broken inheritance at item level (not just library level)? Broken inheritance at item level is almost always a pre-existing mess that should not be carried forward.
What is the schema footprint? How many custom content types? How many custom site columns? How many list views are actually used (last access in 90 days) vs how many exist? The schema will be migrated, so its size needs to be known up front.

Tools that enumerate this quickly: Microsoft 365 admin center reports for basic usage, MigrationFox’s free SharePoint & OneDrive oversharing assessment for permissions, and the Graph contentTypes endpoint for schema. A day is a reasonable budget for the audit on a mid-size tenant. Budget a week for environments that have been inherited and never formally reviewed.

Tenant-level prep

Complete these steps on the destination tenant before the first site migration runs:

Publish sensitivity labels and DLP policies. If the destination tenant does not have labels published, any labeled content from the source lands as unlabeled. Publish first, migrate second.
Set the default sharing policy. New and existing guests only, or Existing guests only, at the tenant level. Migrations inherit the destination tenant’s sharing capability — if the source had Anyone-links and the destination disallows them, the links will not be recreated. That is usually the intent, but it should be a deliberate choice.
Raise relevant limits. The per-user API throttle on Graph is soft, not hard, but a large migration will hit 429s unless the tenant has enough service-principal quota. Open a support ticket to raise app-context throttling before the weekend of the migration, not on it.
Provision destination users and groups. Every UPN in the mapping CSV needs to exist in the destination directory before permissions replay. For fresh tenants, run AD Connect first (or an equivalent) so the principals resolve.

Sequencing: content types first, always

The single most common migration failure is “the files moved and now all the columns are gone”. The fix is sequencing.

The order is:

Site columns. Custom site columns are the leaf dependency for everything else. Enumerate them via Graph, recreate them on the destination site first.
Content types. Content types depend on site columns. Create content types next, binding them to the columns just created.
Lists and libraries. Lists depend on content types. Create the list, attach the content type, and then start writing items into it.
List items and files. With the schema in place, items get correct column values and files land with the correct content type binding.
List views. After items exist, views can be evaluated. Create views last so the CAML filters reference real columns on a populated list.
Pages and web parts. Pages reference lists and libraries. Migrate after item data exists.
Permissions. Always last. Permissions reference everything, so fixing anything earlier in the sequence is cheaper if nothing is locked down yet.

If the chosen tool does not enforce this sequence, teams should enforce it themselves by running the migration in phases. MigrationFox’s Full Site Migration enforces it automatically — the schema phase runs to completion before item writes begin.

Pages and web parts

Modern SharePoint pages are not files; they are canvas layouts with web-part objects. They should be treated as structured data, not as copy-paste HTML.

For each page, the Graph pages endpoint returns a list of web-part instances with their properties (text content, image references, list references, link arrays). A competent migration walks that structure and recreates each web part by type on the destination page, not by scraping HTML.

The one category that needs extra thought is third-party SPFx web parts. If a source page uses a custom SPFx solution, the destination tenant needs the same app package installed — same package ID, same version — before the web part will render. A migration tool cannot install the package on its own (that is a tenant-admin action). What it can do is surface the missing packages in a pre-flight report so they can be installed before cutover.

Version history: trade-offs

Here is the honest truth about version history in a Graph-based migration in 2026: the native version stack on any newly created item starts at version 1.0. Graph does not let a third-party tool write historical versions back into an item’s native version history. That is an SPMT-only capability.

There are two reasonable responses. The first is to accept it and document it. For many migrations, the current-version content plus a clear note in the transition communication is enough. Nobody is going to miss version 4.2 of Q3 2021 Sales Deck.

The second is True History Mode, which is shipped today. When both source and destination are SharePoint, MigrationFox routes the job through Microsoft's SPMT (SharePoint Migration Tool) API under the hood to preserve native version history, the original Author metadata, and Modified/Created dates on the destination item — not to a sidecar library, but on the item itself. Enable True History in the migration wizard when the source and destination are both SharePoint (same-tenant or cross-tenant).

For cross-platform moves — Google Drive to SharePoint, Dropbox to SharePoint, Box to SharePoint — SPMT is not available because it only understands SharePoint content on the source side. In those cases MigrationFox falls back to the sidecar approach where applicable: every source version captured as a JSON record per item (version number, modified-by identity, modified timestamp, field values at that version) written to a _VersionHistory library on the destination site. The native stack on the item itself starts at 1.0, but the audit trail is intact and queryable. For regulated industries migrating from a non-SharePoint source that need to prove what a document said on a given historical date, the sidecar is the defensible artifact.

The trade-off is real: SPMT-backed True History preserves top-level metadata natively for SharePoint-to-SharePoint moves. Cross-platform moves cannot use SPMT, so the sidecar is the fallback path. Promising native metadata fidelity on a non-SharePoint source is dishonest — the source API does not carry the information SPMT would need.

If your migration is SharePoint-to-SharePoint and you need perfect top-level metadata fidelity — typically for records-management use cases with a specific retention audit — True History Mode is the right toggle. If your migration crosses platforms, decide up front whether the sidecar record satisfies the audit contract; if not, an SPMT-only workflow for the SharePoint destination legs may still be feasible.

Cross-tenant UPN mapping

Tenant-to-tenant migrations almost always change user identities. Alice at acme.com becomes Alice at newcompany.com. Every permission assignment in the source references alice@acme.com; every permission replay in the destination needs to land on alice.smith@newcompany.com.

The only reliable way to do this is a mapping CSV maintained by a human who knows the org:

source_upn,destination_upn
alice@acme.com,alice.smith@newcompany.com
bob@acme.com,bob.jones@newcompany.com
marketing-team@acme.com,marketing@newcompany.com

Every source principal in the mapping has an explicit destination. Source principals not in the mapping go on an exceptions list, which the migration tool surfaces before cutover. A tool should never be allowed to silently skip unmapped permissions — that is how sites go live with half their sharing gone, and nobody notices until a user complains three days later.

For groups, destination group memberships come from the directory, not from the migration. If marketing-team@acme.com maps to marketing@newcompany.com, the membership of marketing@newcompany.com must already match the intent before the permission replay runs. Provision groups and populate memberships during the pre-migration phase, not as a migration side-effect.

Post-migration: the 14-day watch

Every SharePoint migration ships with some residual surprises. The recommended practice is a 14-day active watch period:

Keep the source tenant read-only for 14 days so specific items can be re-verified if needed
Monitor the destination tenant’s audit log for “access denied” events on migrated sites — those are permission gaps that slipped through
Run a delta re-sync at day 7 to catch anything edited in the source after cutover (which should be zero if the source is truly read-only, but it is worth verifying)
Run a final exception-list review at day 13 before the source is decommissioned

On day 14, revoke service-principal access on both tenants, rotate any credentials involved, and archive the job report for the audit file.

Get started

Run a free pre-flight on a first site at app.migrationfox.com/register. The dry-run report will show what will migrate, what will land on the exceptions list, and which SPFx packages the destination tenant needs before cutover.