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 labelled content from the source lands as unlabelled. 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 to preserve history as a sidecar. MigrationFox’s approach is to capture every source version as a JSON record per item (version number, modified-by UPN, modified timestamp, field values at that version) and write the collection to a _VersionHistory library on the destination site. The native stack on the item itself resets to 1.0, but the audit trail is intact and queryable. For regulated industries that need to prove what a document said on March 15, 2023, the sidecar is the defensible artefact.

What cannot be done via Graph: overriding modifiedDateTime or the original Author on a new item. Both are set by the server to the service principal and the current time. Capture them in a sidecar or accept the loss. Promising otherwise is dishonest — it implies SPMT-level fidelity from a REST-only tool that cannot deliver it.

If perfect top-level metadata fidelity is a hard requirement — typically for records-management use cases with a specific retention audit — SPMT is the correct tool, not Graph. SPMT-equivalent migrations are on the MigrationFox roadmap but are not shipped today. That trade-off is disclosed up front so teams can make the right call.

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.