SharePoint migrations are one of those projects where confidence from the discovery phase often does not survive contact with the actual environment. The planning looks clean. The source is well-documented. The destination is a fresh tenant. Then the migration begins and a familiar pattern of surprises emerges.
After working with MSPs and internal IT teams who run cross-tenant migrations, tenant consolidations, and content reorganisations, certain failure patterns appear consistently. These are not exotic edge cases. They are the same five problems, in roughly the same order, on almost every project that runs into difficulty.
1 Path Length Problems Surface at the Worst Possible Time
SharePoint Online accepts files with full URLs up to 400 characters. That seems generous. The problem is that Windows OneDrive sync - the tool most users rely on daily to access their files - enforces the old Windows file system limit of 260 characters for the local path. A file that uploads successfully to SharePoint and is accessible in the browser can fail to sync to any Windows device if its local path exceeds 260 characters.
This matters in migrations because source environments, particularly on-premises SharePoint 2013 and 2016 and legacy network file shares, accumulated deep folder structures over years without anyone measuring path lengths. A three-level folder like Projects / Client Name / Project Phase / Documents / 2019 / Q4 / Final Approved Versions / is already pushing 80 characters before the file name is added. Multiply that by a long destination site URL and you have a silent failure waiting to happen.
The fix is to discover path length violations before migration, not after. Run a pre-migration scan that flags every file whose projected destination URL will exceed 260 characters (for sync compatibility) or 400 characters (for browser access). Rename deep folders early, before migration, when the change is straightforward. After migration, renaming requires coordination with users who may already have bookmarks, shared links, and embedded URLs pointing to the old paths.
ShareMaster's Explore Master surfaces hidden properties and full path lengths for items in a SharePoint site, making it practical to audit path lengths before committing to a folder structure in the destination.
2 Permissions Multiply Far Beyond What Anyone Expected
Every SharePoint environment has a theoretical permission model (a clean group structure, a few standard levels) and an actual permission state (years of individual sharing, one-off access grants, and external user invites that were never revoked). The distance between those two things is usually the biggest surprise in a migration assessment.
The SharePoint limit of 50,000 unique permission objects per site collection is not theoretical. Consultants have migrated sites already above this threshold in the source, meaning the destination site collection starts life with a performance problem baked in. It is usually not the result of malicious or even careless behaviour. It is the natural result of a Share button that is too easy to click, link-based sharing that creates a new unique-permission object for each link, and a management model that never included a periodic permission cleanup.
Two things help here. First, run a permission audit before migration and remediate the worst sites. Any library or folder with more than 5,000 unique permission objects is worth consolidating back to inheritance before the content moves. Second, migrate permissions as part of the content move, not as a separate afterthought. Permissions migrated separately tend to drift: a file is restored from the source a week later, a shared link is recreated manually, and the destination's permission state quietly diverges from the source.
For a step-by-step walkthrough of running the audit, see the SharePoint permissions audit guide.
3 Version History Bloat Doubles Transfer Time
Nobody turns off versioning after they turn it on. Versioning is free insurance against accidental overwrites. Over five or ten years, a document library used daily by a team can accumulate tens of thousands of versions across a few hundred files. Many of those versions are from minor edits, auto-saves, or metadata-only changes. The file content has not changed between version 47 and version 48 of a Word document that nobody has opened since 2021.
When you migrate this library, you migrate all versions. The transfer volume can be five to ten times the current file size. The migration time extends proportionally. And the destination tenant inherits a version history that is not meaningfully useful (nobody is going to restore version 47 of a 2019 budget spreadsheet) but that consumes quota and makes future storage reports confusing.
The best time to trim versions is before migration, on the source. A version trim that keeps the last 5 to 10 versions per file reduces transfer volume substantially. It also gives users an opportunity to review and discard draft content they no longer need, before it travels with them to the new environment.
ShareMaster's Space Master Version Trimmer scans version history across all libraries in a site, reports version counts and ages, and trims to a configurable policy without manual library-by-library work. For more background on how version storage accumulates, see the analysis on SharePoint version history storage costs.
4 Microsoft 365 Throttling Is the Invisible Enemy
Microsoft throttles calls to the SharePoint REST API and the Microsoft Graph when a client (a migration tool, a PowerShell script, or a third-party app) sends requests faster than the platform's per-tenant or per-user limits allow. When throttling kicks in, the API returns a 429 (Too Many Requests) response with a Retry-After header telling the client how long to wait before retrying.
Most migration tools handle throttling automatically. The ones that do not, or handle it incorrectly, produce two failure modes: transfers that look like network errors rather than throttle events, and extremely slow migrations because the tool backs off aggressively after each 429 response and does not ramp back up. A migration that should take four hours takes three days because the tool spends most of its time waiting.
A few conditions make throttling worse:
- Too many parallel threads. More concurrent uploads does not always mean faster migrations. At some point you are generating enough API calls to trigger throttling across the board, and all threads stall simultaneously. Back off to 2-4 threads and measure actual throughput before increasing.
- Migrating during business hours. Other tenants share the same Microsoft 365 infrastructure. Migrations running during peak usage hours hit stricter throttle limits. Off-peak windows (nights, weekends) give significantly better throughput.
- Large numbers of small files. Each file upload is multiple API calls: create the item, set metadata, set permissions. A folder of 10,000 small files generates far more API traffic than a folder of 10 large files with the same total size.
The practical response is to schedule bulk migrations during off-peak hours, tune thread counts downward until throughput stabilises, and use a migration tool like Clone Master that implements retry logic correctly and reports throttle events visibly rather than silently grouping them with other errors.
5 Testing on a Sample Site Is Not Optional
The most predictable cause of a blown migration timeline is skipping the test migration. The reasoning is usually time pressure: the cutover date is fixed, the source environment is needed for something else, or the team is confident the tool worked fine on the last project. Then the production migration starts and a problem appears at 2 AM on the cutover weekend that nobody has encountered before.
A sample migration does not need to be a full copy of the source. It needs to be representative. Pick a site that has:
- Files with long paths (close to the 260-character sync limit).
- At least one library with more than 1,000 versions across its files.
- External users in the site's access list.
- Items with unique permissions (broken inheritance).
- Some files with names that include special characters or non-ASCII characters.
Migrate this representative sample to a test destination site first. Verify that files landed in the expected locations, that versions migrated correctly, that permissions resolved, and that destination URLs are within the Windows sync limit. Document every exception the tool reports. Resolve them before the production migration starts.
This process takes half a day. It consistently surfaces problems that would otherwise appear on migration night with no time to fix them. Every hour spent on a test migration saves three or more hours of incident response during the production cutover.
What These Patterns Have in Common
All five of these issues share a root cause: they are invisible until you specifically look for them. Path lengths are not reported by the SharePoint UI. Permission sprawl does not generate alerts. Version counts only appear in library settings, one library at a time. Throttling events are buried in tool logs. Missing test migrations are simply an absence rather than a visible problem.
The migration projects that go well are almost always the ones where someone ran a thorough assessment before the first file moved. They found the long paths, cleaned up the permissions, trimmed the versions, and set throttling parameters conservatively. The projects that struggle are usually the ones where the assessment was brief and the team believed the source was cleaner than it turned out to be.
SharePoint environments accumulate complexity the same way physical offices accumulate clutter. The longer they have been running, the more there is to find before migration. Planning for that reality, rather than being surprised by it, is the clearest differentiator between migration projects that complete on schedule and ones that do not.