How do I migrate a Windows file share to SharePoint Online and OneDrive with Migration Manager?

Key facts

• The agent needs Windows Server 2016 or later (or Windows 10), .NET Framework 4.6.2 or later, 8 GB RAM minimum and 150 GB free disk.
• The source server must support SMB 2.0 or higher.
• Files up to 250 GB are supported for file share to Microsoft 365 migrations.
• After migration, the full path including the file name must be fewer than 400 characters.
• Each agent can have up to 10 tasks in its queue, and you cannot assign a task to a specific agent, only to an agent group.
• Migration Manager reports expire after 90 days, so download them before then.

Prerequisites and licensing

You need two sets of credentials. On the destination side, sign in as a SharePoint Administrator (Global Administrator also works, but use the least privileged role). On the source side, you need a Windows account with Read access to every file share you plan to migrate. Microsoft recommends a dedicated service account that has both, and signing in to the agent machine with it before you install so the agent runs as a service.

If you migrate home drives into OneDrive, pre-provision the OneDrive accounts first. The users must be allowed to sign in and must have a SharePoint license.

• Open outbound HTTPS to the endpoints Microsoft lists, including *.sharepoint.com, *.blob.core.windows.net, *.queue.core.windows.net, *.login.microsoftonline.com, spmt.sharepointonline.com and the scan endpoints such as api.mmp.svc.cloud.microsoft. The agent never opens an inbound port.
• Third-party MFA is not supported for the agent sign-in. Microsoft MFA is.
• Antivirus on the agent can slow migration. If you see submit failures, exclude microsoft.sharepoint.migration.clientservice.exe and microsoft.sharepoint.migration.mthost.exe.
• The working folder %appdata%\Microsoft\SPMigration holds logs and reports and needs at least 150 GB free.

Step 1: Install the Migration Manager agent

Start with one agent. Microsoft suggests a test of 20 to 30 tasks on a single agent to measure throughput, then add only as many agents as your timeline needs. Extra agents raise API traffic and throttling.

1. Sign in to the agent server or VM with the account that has Read access to all source shares.
2. Go to SharePoint admin center > Migration (Migration center).
3. Under For file shares, select Get started.
4. Select the Agents tab, then select Add.
5. Select Download agent setup file and run it.
6. On the Welcome page, choose User Credential Authentication (or Certificate Authentication) and select Next.
7. Enter the SharePoint admin credentials for the destination tenant and select Next.
8. Enter the password for the Windows account that can read the shares, then select Install.
9. Optionally test agent access to a share, then select Close. The agent now appears on the Agents tab.

Step 2: Add sources and review the scan

File shares are scanned automatically when you add them as sources. Scans only run on agents in the Default agent group, so keep at least one agent there.

1. In the file share migration page, open the Scans tab and select Add source path.
2. Enter a UNC path such as \\fileserver\finance (the source path box accepts up to 255 characters), or upload a CSV of source paths.
3. Wait for each scan to finish, then filter the list for Warning or Error results.
4. Select Download summary report for the overview, or highlight a row and select Download scan log to see file-level issues.

Step 3: Copy to Migrations, set destinations and schedule

For many tasks, use bulk upload with a UTF-8 CSV of six columns. All six must be present even when empty. The header row is optional, and only the first 20 rows are checked for valid destinations, so check the rest yourself. For OneDrive targets, use the Documents library and do not add _layouts/15/onedrive.aspx to the URL.

1. On the Scans tab, select one or more ready sources and select Copy to migrations.
2. Choose a destination type: OneDrive, SharePoint or Teams. Select Next.
3. For SharePoint, enter the site URL and pick the library or folder. For OneDrive, enter the user's OneDrive URL or email. For Teams, pick the team and channel.
4. Enter a friendly task name and select an agent group.
5. Review the task settings (see next section).
6. Select Run now and then Run, or select Run later, pick a date and time, and select Schedule.

Settings that matter: permissions, filters and paths

Path length is the setting people trip on most. The final SharePoint path, including file name, must be fewer than 400 characters. Long department folder trees plus a long site and library name can push you over, so plan short site URLs and consider flattening deep folders first.

• Only perform scanning: set On to run a pre-assessment with no data moved.
• Preserve file share permissions: carries NTFS permissions to the migrated files. Microsoft Entra lookup is On by default to map users. Add a user mapping file for accounts that do not match.
• Migrate hidden files: if Off, hidden files are skipped.
• Migrate files created after / modified after: date filters for old content.
• Don't migrate files with these extensions: colon separated, no dot, for example TMP:BAK.
• Migrate files and folders with invalid characters: On by default and recommended. If a package returns more than 100 errors, the whole package is blocked, so clean names before the run.
• Migration auto rerun: scheduled for deprecation. Microsoft recommends Off.

Incremental reruns for cutover

Run the bulk copy while users keep working on the share. At cutover, make the share read-only, then rerun the completed tasks. Delta sync copies only items new or changed since the last run and is faster. Full incremental compares every source item with the destination and catches files added with an older modified date, which delta sync would miss.

Files are matched by path. A source file is not copied if the destination copy is newer, files deleted at the source stay in SharePoint, and destination files that users edited are not overwritten. Do not let users rename or move migrated files before the final pass, because that can lead to overwrites or duplicates.

What does not migrate or is not supported

• Files larger than 250 GB.
• Paths that would exceed 400 characters in SharePoint, and names with invalid characters such as " * : < > ? / \ |.
• Checked-out files fail with error 0x0131000F.
• Content types: files land with the default Document content type, regardless of library configuration.
• SharePoint Server sources: use the SharePoint Migration Tool (SPMT) instead.
• Sites whose title has non-English characters.

PowerShell for site prep and automation

Use the SharePoint Online Management Shell to create destination sites and pre-provision OneDrive before you build tasks. In PowerShell 7, import the module with -UseWindowsPowerShell.

# Connect, create a destination site and pre-provision OneDrive
Install-Module -Name Microsoft.Online.SharePoint.PowerShell -Scope CurrentUser
Connect-SPOService -Url https://contoso-admin.sharepoint.com

# Create the destination site (StorageQuota in MB)
New-SPOSite -Url https://contoso.sharepoint.com/sites/finance -Owner [email protected] -StorageQuota 1000 -Title "Finance"

# Confirm it exists
Get-SPOSite -Identity https://contoso.sharepoint.com/sites/finance

# Pre-provision OneDrive for home-drive users
$users = Get-Content -Path "C:\Users.txt"
Request-SPOPersonalSite -UserEmails $users

# Migration Manager PowerShell module: add a task and pull reports
# Download the module from aka.ms/MMPowerShellModule and unzip it first
Import-Module "C:\MMPS\Microsoft.SharePoint.MigrationManager.PowerShell.dll"
Connect-MigrationService

Add-MigrationTask -TaskName "Finance share" -SourceUri "\\fileserver\finance" -TargetSiteUrl "https://contoso.sharepoint.com/sites/finance" -TargetListName "Documents"

Get-MigrationReport -OutputPath "C:\MMReports" -Status Completed

PowerShell note: SPMT is a different tool

The Register-SPMTMigration, Add-SPMTTask and Start-SPMTMigration cmdlets belong to the SharePoint Migration Tool, not Migration Manager. They run on a single machine without the central admin center queue. They are useful for a one-off share, for example Add-SPMTTask -FileShareSource \\server\share -TargetSiteUrl <site> -TargetList Documents. For multi-share projects, stay with Migration Manager so tasks, agents and reports live in one place.

Common errors and fixes

How to verify it worked

1. In the Migrations tab, confirm every task shows Complete, not Failed.
2. Select the tasks and choose Summary report. In Aggregate Summary Report.csv, compare Total to be migrated items with Migrated items, and check Items not migrated.
3. Open a task and select Download task report. Review ItemFailureReport.csv for each failed file and its error code.
4. Count source files and compare with the ItemSummary.csv Scanned and Migrated values, allowing for filtered items.
5. Spot-check folders in the SharePoint library as a normal user to confirm permissions came across as expected.

# Count files at the source, including hidden files
(Get-ChildItem -Path "\\fileserver\finance" -Recurse -File -Force | Measure-Object).Count

When to call a consultant

Tell us how many shares and users you have. We will tell you on a short call whether you can handle it in-house or want help with the plan and cutover.

Take the 2-min fit check Talk to a specialist

How Accred Consulting approaches it

We start with a free call to size the shares and agree on scope, then quote fixed-fee or hourly. You get a written plan that maps each share to a site or library, flags long paths and permission sprawl from a scan-only run, and sets the cutover window. We pilot one department first, check the reports with you, then run the bulk copy and the incremental cutover. Our US-based team stays on through the first days after cutover to fix access issues and clean up anything the reports flag.

Track record: 475+ client projects, 2,000+ migration workstreams and 210,000+ users migrated by a US-based team. Company facts · Case studies

Related questions

Sources

• Microsoft Learn: Migration Manager prerequisites and endpoints
• Microsoft Learn: Setup Migration Manager agents
• Microsoft Learn: Copy to migrations for file share migration
• Microsoft Learn: Troubleshooting Migration Manager