Migrating File Servers to SharePoint and OneDrive the Right Way

Mail is the visible part of a Microsoft 365 migration. The file server is the part that takes longer, because the data is bigger, the structure is older, and every department has a folder tree nobody wants to change. Done badly, the result is a slow mapped drive with worse permissions.

This post covers how to plan the structure, run Migration Manager, deal with permissions and limits, and decide what should not move at all.

Decide the target structure before the tool

SharePoint is not one big drive. It is many sites, each with document libraries, and Teams sits on top of those sites. The mapping you choose from folders to sites is the most important decision in the project and no tool makes it for you.

Keep libraries reasonably flat and under a few hundred thousand items each. Deep folders with long names hit the path length limit, and libraries with millions of items are slow to sync and search.

Decide who owns each site and what the permission model is. SharePoint permissions work best at the site or library level with a small number of groups.

• Department shares: one SharePoint site per department, possibly Teams-connected.
• Home drives: each user's OneDrive, with Known Folder Move for Desktop and Documents.
• Project archives: a dedicated archive site with read-only permissions.
• Application data, databases, scan folders: stay on a server or move to Azure Files.

Migration Manager and the SharePoint Migration Tool

Migration Manager lives in the SharePoint admin center. You install an agent on one or more Windows machines that can reach the file shares, and the service coordinates scans and migrations across them. The SharePoint Migration Tool, SPMT, is the desktop version for smaller jobs and one-off moves, and it has a PowerShell module for scripting.

Both do the same basic work: read the source, check every file against SharePoint's rules, copy the content with timestamps and author metadata preserved, and optionally map NTFS permissions to SharePoint permissions. Both can run a scan first with no copy.

1. Install the Migration Manager agent on a server near the data, signed in with an account that can read every share.
2. Add the source paths and run a scan only. Read the scan report.
3. Fix or exclude what fails: invalid characters, paths over the limit, blocked file types, files over the size limit.
4. Map each source to a site and library, and run a first migration while users keep working.
5. Run incremental passes until the delta is small, then freeze the share, run the final pass, and switch users.

Import-Module Microsoft.SharePoint.MigrationTool.PowerShell
$cred = Get-Credential
Register-SPMTMigration -SPOCredential $cred -Force
Add-SPMTTask -FileShareSource "\\fs01\Finance" -TargetSiteUrl "https://tenant.sharepoint.com/sites/Finance" -TargetList "Documents"
Start-SPMTMigration
Get-SPMTMigration | Select Status, CurrentTaskScanned, CurrentTaskMigrated, CurrentTaskFailed

Permissions, limits and things that break

The scan report tells you exactly which files will not move. Common blockers are characters in names that Windows allows and SharePoint does not, paths that exceed the limit once the site URL is prepended, files above the single-file size cap, and file types blocked by the tenant. Fix these at the source with a rename script.

Permissions are the harder problem. Migration Manager can translate NTFS ACLs into SharePoint permissions, but only for users and groups that exist in Entra ID with matching identifiers, and only up to the limit of unique permissions per library. A better approach is to set the site permissions to the right groups first and let content inherit, then restore a handful of restricted folders by hand.

Files locked open during a pass are skipped and picked up on the next, so the incremental run is not optional.

• Rename files and folders with invalid characters before the final pass.
• Shorten deep paths: total URL length is what counts, not just the file name.
• Break the connection between OneDrive sync and the old mapped drive on the same day so users do not work in both.
• Do not migrate permissions blindly; design the groups first.

What should not move to SharePoint

Some data is not documents. Access databases, QuickBooks company files, CAD assemblies with linked references, scanner drop folders, and applications that write to a share with file locks do not belong in SharePoint. They stay on a file server, move to Azure Files, or move to the vendor's hosted version.

Very large archives that nobody opens are a judgment call. Cold data is cheap on a NAS and expensive in SharePoint storage above the included allowance. For tens of terabytes, price the storage first.

The user side: sync, Known Folder Move, and the old drive letter

Users experience the file migration through the OneDrive sync client. Push Known Folder Move by policy so Desktop and Documents land in OneDrive automatically, and let people add the department libraries through the Sync or Add shortcut button in SharePoint. Keep the number of synced libraries per person small.

Remove the drive mapping on cutover day. If the old share stays reachable, half the office will keep saving there for months. Set it read-only for two weeks, then take it offline.

Frequently asked questions

Takeaway

The file migration is decided by structure and permissions, not by the tool. Design the sites and groups, run the scan and fix the source, then let Migration Manager copy in passes until cutover. Leave application data on a server, remove the old drive letter on day one, and use Known Folder Move so personal files land where they should.