SharePoint → SharePoint: which mode to use

Three modes, very different trade-offs. Pick the one that matches what you need to preserve, how big your largest files are, and how fast you need to finish.

See also: Schema-aware coverage — what migrates vs. what needs the one-click toggles, and the cross-tenant web-part fix-up matrix.

Decision tree

Do you need to preserve original timestamps, authors, or version history?
├─ NO  → Standard File Migration (fastest, simplest)
└─ YES → Do you also need lists / views / content types preserved?
         ├─ NO  → Standard File Migration (versions migrate via per-file replay)
         └─ YES → Do you have files > 1 GB?
                  ├─ YES → Site Migration without True History Mode
                  │         (large files succeed; loses original timestamps/authors)
                  └─ NO  → Site Migration with True History Mode (SPMT)
                            (highest fidelity)

Mode 1: Standard File Migration

Streams files one by one from source SharePoint to destination via Microsoft Graph. Optionally replays version history via per-file version uploads.

What’s preserved

• File content (exact bytes)
• File names & folder hierarchy
• File version history if “Migrate version history” is checked — replayed via separate uploads
• Permissions (basic; some inheritance edge cases may not preserve perfectly)

What’s lost

• Original Created timestamp (replaced with migration time)
• Original Created by (replaced with the migrating user / service principal)
• Lists, list items, columns, content types
• Site pages, navigation, themes
• Site-level audit logs / compliance metadata

Use when

• Migrating specific libraries or a folder, not the whole site
• File contents matter; metadata doesn’t
• Files larger than 1 GB exist in the source
• You need the fastest possible migration
• You’re moving content into an existing destination site (just adding files)

Don’t use when

• Compliance / audit requirements demand preservation of original authors / timestamps
• You need to replicate the entire site (lists, views, content types)
• Source has structural elements (custom lists, schemas) you need at the destination

Speed & limits

Throughput: 200–800 GB/day on a healthy connection, throttled by Graph API limits and bandwidth. No practical per-file cap (handles multi-GB files via streaming). SharePoint Online tenant max applies (~250 GB/file).

Mode 2: Site Migration (without True History Mode)

Migrates the entire site structure — libraries, lists, content types, views, page library — using Microsoft Graph for the structural elements and Standard File Migration (Mode 1) for file content.

What’s preserved

• Library structure (folders, names)
• List schemas (columns, content types, validation rules)
• List items (with original column values)
• List views (column orders, filters, sorts)
• Site pages (when “Migrate Site Pages” is enabled)
• Permissions (best-effort; group memberships migrated where possible)
• File version history (when toggle on, via per-file replay)

What’s lost

• Original Created / Modified timestamps for FILE CONTENT (list items can preserve theirs)
• Original Created by / Modified by for files
• Workflow definitions (SharePoint Designer / legacy)
• Site-level audit logs

Use when

• M&A — combining two SharePoint sites into one consolidated site
• Site reorganization (moving site to new tenant; restructuring)
• You need lists, columns, content types replicated
• Files larger than 1 GB exist in the source (this mode handles them where True History Mode wouldn’t)
• File metadata fidelity is less critical than overall site structure

Mode 3: Site Migration with True History Mode (SPMT)

Uses Microsoft’s official SharePoint Migration API (SPMT, also called PRIME). Encrypts file content and stages it in Azure Blob Storage; submits a manifest to SharePoint Online; SPO ingests files with full fidelity preservation.

What’s preserved

• Everything from Mode 2, plus:
• Original Created / Modified timestamps on files
• Original Created by / Modified by attribution
• Full version history with original version timestamps and authors
• Compliance / audit metadata (where SPMT supports it)
• “True” migration evidence visible in SPO admin tools

What’s lost

• Files larger than 1 GB (currently pre-skipped — current MigrationFox version limit; SPMT itself accepts much larger files)
• Files with destination URL > 400 chars (SPO hard limit; pre-skipped with warning)
• Files with names containing ~ " # % & * : < > ? \ / (SPO blocks these)

Use when

• Compliance / regulated industries — SOX, HIPAA, GDPR retention requirements that require original audit trail to be preserved
• M&A integration with proper paper trail of original ownership / authorship
• Tenant-to-tenant migrations (most common SPMT use case)
• Trust / credibility requirements with the destination — original “who created this when” matters

Don’t use when

• Files larger than 1 GB exist (will be pre-skipped — manually copy via Mode 2)
• Path lengths approach SPO’s 400-char limit (pre-skip will catch them, but you waste staging time)
• Destination is on a different tenant where you don’t have full admin (SPMT requires elevated permissions)
• You need migration to complete fast (Mode 3 is the slowest of the three)

Operational notes

• Destination site may be temporarily unavailable to interactive browsing during SPO’s ingestion phase (“Something’s not right” page = normal, wait it out)
• Worker may be busy for many minutes between staging-complete and SPO-ingestion-complete (intentional)

Quick reference

Capability	Mode 1: File Migration	Mode 2: Site Migration	Mode 3: Site Migration + True History
File contents	Yes	Yes	Yes
Folder structure	Yes	Yes	Yes
Lists / columns	No	Yes	Yes
Content types	No	Yes	Yes
List views	No	Yes	Yes
Site pages	No	Yes (toggle)	Yes (toggle)
File Created date	migration time	migration time	original
File Created by	service account	service account	original
File version history	Yes (toggle, replay)	Yes (toggle, replay)	native SPMT
Files > 1 GB	Yes	Yes	pre-skipped
Speed	Fast	Moderate	Slower
Best for	Specific libraries	Site consolidation	Compliance / fidelity

Common questions

Can I run True History Mode for the libraries that fit, then File Migration for the > 1 GB files?

Yes — this is the recommended pattern for mixed workloads. Run Site Migration with True History Mode first (skips files > 1 GB with clear warnings), then run a Standard File Migration scoped to just those skipped files. Combined result: site structure + version history for normal files, plus the big files migrated separately.

My users see “Something’s not right” when browsing the destination during migration. Is this broken?

No — that’s SharePoint Online’s expected behavior during SPMT ingestion (Mode 3). It self-resolves within 10–60 minutes after the migration completes. Don’t refresh aggressively; that extends throttling.

Why does Mode 3 say “1 GB” file cap? My SPMT documentation says SharePoint accepts up to 250 GB.

The 1 GB cap is a current MigrationFox worker constraint — large files cause memory pressure during AES staging on the current worker tier. SPMT itself accepts much larger files. The cap will lift in a future MigrationFox release when the worker moves to multi-instance / larger heap.

How do I know which mode my migration job is using?

Check the job’s Configuration card on the Job Detail page:

• “Mode: File Migration” → Mode 1
• “Mode: Site Migration” with True History Mode = OFF → Mode 2
• “Mode: Site Migration” with True History Mode = ON → Mode 3

Can I switch modes mid-migration?

No — modes are set at job creation. To switch, cancel the current job and create a new one with the different mode.

Related

• SPMT True History Mode reference — metadata preservation deep-dive
• SharePoint site migration overview
• Migration Rehearsal — runtime prediction before the real run