SharePoint Migration Mistakes to Avoid (and How to Fix Them)

Most SharePoint migrations don’t fail on the big day. They fail on small decisions nobody made: a wrong option on a wizard screen, a permissions toggle left alone, or a folder structure that lands one level deeper than anyone expected.

In this tutorial, we’ll walk through the SharePoint migration mistakes I hit while testing the SharePoint Migration Tool (SPMT) against our /sites/SPGuides site, then the ones Microsoft warns about most. For each one, you’ll see what happens and exactly how to fix it.

Quick answer: Pick the right SPMT method (a CSV file needs Bulk migration using JSON or CSV file), decide on permissions before you start because Preserve file share permissions is Off by default, plan where the root folder lands, and clean up invalid names, 400-character paths and files over 250 GB first. Run a small pilot, migrate outside business hours, and tell users before cutover.

Mistake 1: Picking the CSV file as a single file share source

This was the first thing that tripped me up. I had a CSV listing two sources, chose Single file share source, and pasted the CSV path into the source box. SPMT replied with “This folder does not exist or cannot be opened. Please try again.” and the Next button stayed disabled.

The single source option only accepts a folder. Fix: select Back, choose Bulk migration using JSON or CSV file, and enter the CSV path there. My two-row CSV then migrated 10 of 10 items in about 1 minute. If SharePoint terms like site, library and folder are new to you, the SharePoint tutorials hub is a good primer.

Mistake 2: Ignoring the “Slow connection between SPMT and Azure” note

My first run finished 6 out of 6 files (183.99 KB) in 1 minute, yet the completed page still showed “Slow connection between SPMT and Azure is affecting performance.” On six small files it didn’t matter. On a 2 TB file server, the same bottleneck turns a weekend job into a week.

SPMT uploads your content to Azure blob storage first, then the Migration API moves it into SharePoint. Microsoft’s performance guidance points to three places to check:

• Network to Azure: give the migration computer more bandwidth, use a machine with fast network access, and stop other apps that compete for the connection.
• Reading the source: Microsoft says this is the typical bottleneck. Run SPMT close to the file server, or on it, and keep antivirus scans from fighting it for disk and CPU.
• The migration computer: a fast SSD helps, and the working folder should sit on the fastest disk.

Timing matters too. Background apps like migration tools get tighter throttling during weekday business hours, and a support ticket won’t lift it. Schedule big batches for evenings and weekends. Before you start, check each document library size so you know which batches are the heavy ones.

Mistake 3: Not planning where the root folder lands

In a single source migration, the default option is Migrate selected folder and folder contents. I pointed it at a folder called SPGuides Policies and the Migration Demo library ended up with a top-level SPGuides Policies folder, with HR, Finance and a holiday calendar inside it.

Users often expect the files at the library root. Choose Migrate only folder contents to skip that extra level. In PowerShell, the matching switch is -MigrateWithoutRootFolder.

The bulk CSV behaved differently. When I set a target subfolder, the contents of the source landed straight in Policies and Marketing, with no extra SPGuides Policies level:

Fix: sketch the target library and folder tree before the first run, then pick the option that produces it. Deep folder trees also make long paths, so see these document library best practices for when metadata beats folders.

Mistake 4: Leaving file share permissions on the defaults

On the Review settings screen, SPMT showed three toggles: Only perform scanning Off, Preserve file share permissions Off, and Automatic user mapping On. Click Start without thinking, and every migrated file simply inherits the library’s permissions.

That can expose HR files to the whole site. Fix: decide first. If you turn preservation on, know that explicit deny entries and advanced NTFS permissions don’t carry over. I’d rather rebuild access with SharePoint groups, following SharePoint permissions best practices, and keep unique permissions well under Microsoft’s recommended 5,000 per library.

Also check accounts that won’t match automatically, such as former employees or local accounts. SPMT supports a user mapping file for those.

Mistake 5: Using -SPOUseEntraAuth without custom Azure storage

-SPOUseEntraAuth needs $true, and even then Register-SPMTMigration stopped with an error because Entra authentication in PowerShell requires your own Azure storage:

# Fails: Entra auth in PowerShell without your own Azure storage
Register-SPMTMigration -SPOUseEntraAuth $true -Force
# [-UseCustomAzureStorage] is required to be true when using [-SPOUseEntraAuth]

# Works: register with a credential instead
$SPOCredential = Get-Credential
Register-SPMTMigration -SPOCredential $SPOCredential -Force

Fix: either set up custom Azure storage and pass -UseCustomAzureStorage $true, or register with -SPOCredential. For a handful of files, uploading files with PnP PowerShell is often quicker than SPMT.

Other SharePoint migration mistakes Microsoft warns about

Migrating everything without cleanup

Microsoft’s guide says to sort content into redundant, out of date or still relevant, and to run an Only perform scanning pass first. The scan report shows problem files before any copy starts.

Ignoring invalid names, path length and big files

Limit	What blocks the file	Fix
Invalid characters	" * : < > ? / \ |, leading or trailing spaces	Rename, or turn on Replace invalid filename characters
Blocked names	CON, PRN, AUX, NUL, COM0-9, LPT0-9, .lock, desktop.ini, _vti_, ~$ prefix	Rename at the source
Path length	Decoded path over 400 characters, file name included	Shorter library and folder names, flatter trees
File size	Over 250 GB per file	Archive or split before migrating

With Replace invalid filename characters off, SPMT skips those files, and a package with more than 100 errors is blocked along with its valid files.

Dumping huge folders into one library

A library holds up to 30 million items, but views still hit the 5,000-item list view threshold. Users then see the list view threshold error. Split large shares into focused libraries and build indexed, filtered views.

Expecting workflows and InfoPath forms to come across

SPMT can’t migrate InfoPath forms, master pages or custom New/Edit/View forms. SharePoint 2010 workflows were retired in 2020, and SharePoint 2013 workflows were fully retired on 04/02/2026. Plan Power Automate replacements early; my SharePoint Designer workflow replacements guide maps common workflows to flows.

Migrating every version, skipping the pilot, and forgetting users

Migrating all file versions slows the job and eats storage, so set a version count, then review versioning settings in SharePoint Online. Run a pilot on one small share. And tell users early: Microsoft’s guide says to communicate early and often, and the full timeline lives in the SharePoint Migration Checklist (Before, During and After) post.

Common errors and how to fix them

What you see	Cause	Fix
“This folder does not exist or cannot be opened”	CSV path in Single file share source	Back, then Bulk migration using JSON or CSV file
“Slow connection between SPMT and Azure”	Bandwidth, source reads or disk	Faster network and SSD, off-hours batches
Extra top-level folder	Migrate selected folder and folder contents	Migrate only folder contents, or -MigrateWithoutRootFolder
Files missing after the run	Invalid names, long paths, size limits	Read the Report folder, fix, rerun
“[-UseCustomAzureStorage] is required…”	-SPOUseEntraAuth without custom storage	Use -SPOCredential or your own Azure storage

After every run, select View reports. It opens a WF_ folder with Log and Report subfolders that list each skipped file and why. Then check site permissions in SharePoint Online before you invite users in. The SPMT step-by-step and bulk CSV posts walk through both runs in full.

Once your content is in SharePoint, these guides help you keep it tidy and secure:

• When to Use OneDrive vs SharePoint for File Storage
• SharePoint Contribute vs Edit Permissions: Key Differences and Best Uses
• Get SharePoint Folder Permissions Using PnP PowerShell
• How to Create Site Retention Policies in SharePoint

Frequently Asked Questions