SharePoint Migration Tool (SPMT) Limits: What Actually Breaks

Microsoft's SharePoint Migration Tool (SPMT) is free, first-party, and genuinely useful for straightforward file share moves — until it isn't.

SPMT enforces hard limits on file sizes, path lengths, permissions, and version history that silently break migrations at scale. For basic, flat file migrations under a few terabytes, it works. Apply SPMT to enterprise environments — deeply nested folder structures, decades of version history, custom web parts, complex permission models — and it drops data, throttles to a crawl, and leaves you with weeks of post-migration remediation.

This guide documents every constraint that matters, what happens when you hit them, and how to evaluate whether you need a third-party tool or a managed migration service.

For a companion piece on getting data into SharePoint, see How to Import Data into SharePoint: Methods, Limits & Tools. If you're migrating from Confluence specifically, see Confluence to SharePoint Migration: Data Mapping, Limits & Tools — SPMT does not support Confluence as a source.

What Is the SharePoint Migration Tool (SPMT)?

SPMT is Microsoft's free, downloadable migration application for moving content from on-premises environments into SharePoint Online, OneDrive, and Teams.

SPMT supports these source environments:

• On-premises file shares (local and network, SMB)
• SharePoint Server 2010, 2013, 2016, and 2019
• SharePoint Foundation 2010 and 2013

SPMT operates by packaging source data, uploading it to Azure blob storage, and using the SharePoint Migration API to ingest data into the target tenant. This asynchronous process handles bulk file transfers efficiently. But SPMT is fundamentally a lift-and-shift tool. It does not restructure your information architecture, does not map complex metadata on the fly, and is strictly bound by SharePoint Online's API limits.

SPMT's strongest use case is file share to SharePoint Online migration. It handles bulk document migration with metadata preservation, supports incremental migration (delta sync), and integrates with Migration Manager in the SharePoint admin center for centralized scheduling and monitoring.

SPMT also cannot support cross-tenant migration — moving SharePoint Online sites, document libraries, metadata, Teams workspaces, or OneDrive files from one Microsoft 365 tenant to another.

If you're still on SharePoint Server 2019, this isn't abstract planning. Extended support ends July 14, 2026. Teams under deadline are the teams most likely to over-trust a free tool and under-budget cleanup. See our Microsoft 2026 End-of-Support Timeline for the full picture.

The 5 Hard SPMT Limits That Break Migrations

These aren't soft warnings. They're hard constraints enforced by either SPMT itself or the SharePoint Online platform. Hitting any of them during a production migration means skipped items, manual remediation, or a full restart.

1. 250 GB Maximum File Size

The maximum file size supported by SPMT is 250 GB — whether migrating from SharePoint Server or file shares. This matches the SharePoint Online platform limit.

While 250 GB sounds massive for standard office documents, enterprise environments frequently house large CAD files, raw video archives, PST archives, SQL database backups, and disk images (ISOs) on network drives. If a file exceeds this limit, SPMT cannot chunk or compress it. The file is rejected by the Migration API with no workaround. You must identify these files during pre-migration discovery and route them to alternative storage — Azure Blob Storage, AWS S3, or a dedicated media library.

Files approaching the ceiling also migrate slowly and are more prone to network-timeout failures.

2. 400-Character File Path Limit

SharePoint Online enforces a 400-character limit on the full file path. This includes the entire URL after the tenant domain:

https://tenant.sharepoint.com/sites/sitename/Shared Documents/Folder/Subfolder/Filename.docx

This is where most file share migrations break. URL encoding expands characters: a single space becomes %20 (three characters instead of one). Special characters like #, &, and accented characters expand similarly. A folder path that looks like 250 characters in Windows Explorer can exceed 400 characters in the cloud — especially given that local Windows paths support up to 32,767 characters via extended-length paths.

When SPMT encounters a path that exceeds the limit, it skips the file and logs an error. It does not attempt to retry the file. It does not flatten the path for you. You're left locating the failed files manually via ItemFailureReport.csv and restructuring your folder hierarchy before re-running.

Deep folder hierarchies from legacy file servers — the classic \\server\department\team\project\year\client\subfolder\subfolder\document.docx pattern — are the most common casualty. If you don't review failure reports before cutover, path problems become missing-content complaints from users on day one.

3. ~500 Version History Cap Per Item

SPMT supports version history migration. You can choose to migrate only the latest version, all versions, or specify a number. In practice, the commonly applied maximum is around 500 major versions per item — a default that aligns with SharePoint's version-storage guidance.

For document-heavy libraries where versioning has been enabled for years, this means the oldest history gets silently truncated. If your compliance or audit requirements mandate full version history, you need to plan accordingly.

The bigger problem is performance. Migrating version history multiplies the work. If a single 10 MB Word document has 100 versions, SPMT doesn't just migrate the current state — it executes API calls to process 100 separate file uploads to rebuild the history in the cloud. Enabling "migrate all versions" on a legacy SharePoint 2013 environment can turn a weekend migration into a multi-week ordeal, compounding throttling and timeout risk.

Baseline file share migration throughput is roughly 1–2 TB per 24 hours per agent (many small files reduce throughput by 60–70%). Layering full version history on top of that slows things dramatically. Decide your version policy before the first full run.

4. 100,000-Item Performance and Permission Threshold

While SharePoint Online document libraries can technically hold up to 30 million items, SPMT migration jobs degrade severely or fail outright when a single list or library exceeds 100,000 items.

At this threshold, Microsoft's dynamic API throttling kicks in to protect the multi-tenant infrastructure. Migration speed drops from gigabytes per hour to a crawl, generating 429 Too Many Requests errors. When a library contains more than 100,000 items, you also can't break permissions inheritance on the list or library itself — a hard platform constraint that blocks permission-modifying calls regardless of retry logic.

The permission scope angle matters here too. Every broken inheritance point adds a unique scope (a uniquely secured object with its own ACL). Microsoft recommends staying under 5,000 unique permission scopes per library for acceptable performance, with a hard limit of 50,000 unique scopes. If your source has heavy per-folder or per-file unique permissions in a large library, you'll hit permission scope limits well before you hit item count limits.

If you have large document libraries, restructure at the source — split into multiple libraries or folders with fewer than 100,000 items each — before SPMT can reliably process them.

5. Limited Error Reporting and No Automatic Retry

SPMT provides downloadable spreadsheet reports after each migration run. For small migrations, this is adequate. At scale, it becomes painful.

The minimum set of reports to review after every run:

- SummaryReport.csv
- FailureSummary.csv
- ItemFailureReport.csv
- ItemReport.csv
- ScanSummary.csv

These are flat files. For a migration with hundreds of thousands of items, triaging failures requires manual forensics. Determining whether a failure was caused by throttling, a permission mismatch, a path-length violation, or a transient network error means inspecting individual records.

Critically, SPMT does not automatically retry failed items. If a file fails, it hard fails. You need to identify it, fix the root cause, and re-run. This limited customization, minimal reporting, and basic error handling make SPMT significantly harder to operate in complex projects.

Why SPMT Fails at Permissions and Custom Workflows

Data volume is half the migration challenge. The other half is security and functionality — and this is where the gap between "works for a small file share" and "enterprise production migration" becomes a chasm.

Permissions: Deny and Inherited Are Dropped

SPMT migrates basic permissions — Read, Write, and Full Control from file shares, and unique (non-inherited) permissions from SharePoint Server. But it drops several critical categories:

• Deny permissions are not saved. Legacy file shares and on-premises SharePoint environments often use explicit "Deny" ACEs to block specific users or groups from sensitive folders. SharePoint Online doesn't support explicit Deny in the same way, and SPMT simply drops these rules. If you rely on Deny rules to secure HR or finance folders, migrating with SPMT will expose that data to wider groups. In regulated environments, that's a compliance violation.
• Inherited permissions are not migrated. Only unique permissions survive the move.
• Active Directory group mapping is limited. SPMT can only migrate default SharePoint groups. If your organization uses AD groups, you can't use SPMT to map them to SharePoint groups in the target site, and you can't map a SharePoint Server group to a SharePoint group.

If your source has heavily customized permission structures with broken inheritance — subfolders with unique permissions different from their parent — SPMT often fails to map those accurately to the destination, especially when source Active Directory UPNs don't perfectly match target Entra ID (Azure AD) User Principal Names.

For a deeper dive on rebuilding your security model post-migration, see The Definitive Guide to SharePoint Permissions & Security (2026 Edition).

Workflows: Partial Support at Best

The workflow story is messy enough to deserve suspicion. Microsoft's SPMT overview page says SharePoint Designer 2010 and 2013 workflows can be migrated to Power Automate (added in SPMT 4.1). But Microsoft's current workflow-migration PowerShell page says SharePoint Designer and SharePoint Server 2013 workflows are "not currently supported." When Microsoft's own docs disagree, do not promise timelines based on best-case assumptions. Pilot it.

What's definitively not migrated:

• Workflow history — approval records, run logs, and audit trails are dropped. If your compliance posture requires queryable approval history, export that data before migration.
• Nintex workflows and any third-party workflow logic.
• Running workflow instances.

Custom Web Parts and Solutions

If you're migrating from SharePoint 2010 or 2013, your environment likely relies on InfoPath forms, custom farm solutions (WSPs), and classic web parts. SPMT will migrate raw list data, but the business logic, UI customizations, and automated routing stay behind.

Microsoft's supported web parts table marks many classic components as unsupported — InfoPath Form web parts, Excel Web Access, many Business Data web parts, and search-driven parts. Some web parts require custom script to be allowed on the tenant, and that setting can take up to 24 hours to apply.

Microsoft requires you to rebuild unsupported solutions using Power Automate, Power Apps, and modern SharePoint web parts. Budget significant time for post-migration reconstruction.

SPMT vs. ShareGate vs. AvePoint vs. Quest: Choosing the Right Tool

SPMT's limitations push many teams toward third-party alternatives. Here's how the major options compare based on published benchmarks and feature sets:

Throughput figures based on published benchmarks from Collab365 and EPC Group testing on 10 TB datasets during off-peak hours.

ShareGate (now part of Workleap) has been the go-to migration tool for SharePoint consultants since 2012. Its desktop interface lets administrators map permissions visually, flatten folder structures to avoid the 400-character limit, and run detailed pre-migration reports showing permission deltas. If maintaining exact permission structures matters — compliance, legal holds — ShareGate provides the most granular permission mapping available.

AvePoint Fly targets large enterprise environments — multi-tenant migrations, deep governance features, and compliance with corporate retention policies. It uses bulk APIs plus Azure Blob and app tokens to reduce throttling impact.

Quest Content Matrix (formerly Metalogix) handles the most complex legacy SharePoint migrations. It provides distributed execution and restructuring capabilities with granular metadata filtering, though it requires significant training to operate effectively.

The honest truth: most enterprise migrations use multiple tools. A common pattern is SPMT + Migration Manager for file share content (typically 40–60% of total data volume), ShareGate or AvePoint for SharePoint-to-SharePoint content with complex permissions and metadata, and custom scripts for edge cases.

The useful comparison isn't free vs. paid. It's lift-and-shift vs. remediation, restructuring, and program control.

The Hidden Cost of DIY PowerShell + SPMT

A common pattern: teams discover SPMT's limitations mid-migration and try to fix them with custom PowerShell scripts. All SPMT functionality is exposed as PowerShell cmdlets via Register-SPMTMigration, which sounds promising. In practice, it creates different problems without solving the original ones.

PowerShell doesn't change the limits. The PowerShell module is the same migration engine exposed as cmdlets. It's useful for orchestration and automation, but it does not make path limits, permission-scope limits, throttling, or unsupported customizations disappear.

Throttling is non-negotiable. Microsoft 365 throttling is dynamic and can reduce migration throughput by 50–80% during peak hours (8 AM – 6 PM in your tenant's region). Throttling rules can't be disabled or suspended. Opening a support ticket doesn't lift throttles. Real-world reports from the Microsoft Tech Community document migrations where approximately 50% of sessions failed — and even completed sessions took over an hour for 50–100 MB packages.

Error logs become unmanageable at scale. When you're scripting hundreds of migration tasks, the flat spreadsheet reports don't aggregate cleanly. Diagnosing whether a failure was throttling, a permission mismatch, a path violation, or a transient network issue requires per-item, per-task log forensics.

# Typical SPMT PowerShell pattern — looks simple, breaks at scale
Register-SPMTMigration -SPOCredential $cred -Force
Add-SPMTTask -FileShareSource "\\server\share" `
  -TargetSiteUrl "https://tenant.sharepoint.com/sites/target" `
  -TargetList "Documents"
Start-SPMTMigration
# What the script doesn't handle: throttling backoff,
# path-length pre-validation, permission delta reporting,
# or automatic retry on transient failures.

The "free" tool costs engineer-hours. Teams regularly spend 3–4 weeks of senior engineer time babysitting SPMT + PowerShell migrations that a purpose-built tool or managed service could complete in days. The license cost of ShareGate ($5,995/year) or a managed migration service often costs less than the loaded salary of an engineer burned on troubleshooting.

Operational gotchas you won't find in the feature list: SPMT's working folder defaults to %appdata%\Microsoft\MigrationTool and needs at least 150 GB free space — often more depending on migration size. If you use your own Azure Storage, bandwidth charges apply. And if your environment sits behind a proxy, SPMT does not support proxy connections by default — you'll need to edit the config or face sign-in and library-loading errors.

When SPMT Is the Right Choice

SPMT isn't a bad tool. It's a limited one. It's the right choice when:

• Source is a file share under ~10 TB with flat or shallow folder structures
• Permissions are simple — Read/Write/Full Control, no Deny ACEs, no complex AD group nesting
• Version history isn't critical or you're fine with the ~500 version cap
• No custom workflows, web parts, or third-party solutions need to migrate
• Budget is zero and timeline is flexible enough to accommodate manual remediation

If that describes your project, use the free tool and spend your budget elsewhere.

For anything beyond that — deep folder hierarchies, complex permission models, large document libraries, Nintex workflows, cross-platform sources, or migrations requiring zero downtime — you need a third-party tool, a managed migration service, or both.

How ClonePartner Handles What SPMT Can't

We see the same pattern repeatedly: teams start with SPMT, hit the limits documented above, and come to us mid-project needing rescue.

What we do differently:

• Path-length pre-validation and intelligent remapping — we scan source environments for path-length violations before migration starts, then programmatically flatten or rename paths while preserving metadata so users can still find their documents.
• Full permission fidelity — we map complex ACLs including Deny logic, inherited permissions, and nested AD group structures to Entra ID in the target environment. No sensitive data is inadvertently exposed.
• Parallel API execution beyond SPMT's throughput ceiling — for 100,000+ item libraries, we use optimized batch processing that works within Microsoft's throttling framework without the burst-and-stall behavior SPMT exhibits.
• Unsupported sources — SPMT doesn't support Confluence, Notion, Coda, or other non-Microsoft platforms. We do.
• Zero downtime — we run incremental syncs and cut over during off-hours so your team never stops working.

SPMT rarely fails because it's bad. It fails because the project needs more engineering than a free wizard was built to provide.