GOVERNANCE · April 15, 2026 · Updated November 6, 2026 · 9 min read
10 things that break SharePoint migrations (and how to catch them before cutover)
Cutover day is when the surprises arrive. Permission gaps. Blocked file types. Workflow dependencies. Path lengths that exploded the moment you rebased under a longer destination URL. A content type with a site column that has the same internal name as a tenant-level field. A folder of training videos that quietly exceeds a per-library size limit nobody told you about.
Ten failure categories cover almost every SharePoint cutover-day breakdown. The symptoms vary (rollback at 02:00, half the items skipped, permissions silently dropped, a Monday morning of cleanup tickets), but the root cause almost always falls into one of ten buckets. Here is what they are, why they break, and how to find each one in advance.
The 10 failure categories
The first nine match issue categories in the Migration Rehearsal report; the tenth (data integrity) is not something Rehearsal checks today. They are listed in the order you tend to encounter them on a real migration: structural conflicts surface first, then content-shape problems, then runtime risks.
| Category | What it means | Typical fix |
|---|---|---|
| Schema mismatch | A source content type or site column conflicts with a destination-tenant definition of the same name but different schema | Rename on source before migration, or map to a new destination name |
| Permission risk | A permission assignment references a principal that does not exist in the destination tenant | Map the principal, or add a cross-tenant user mapping table |
| Blocked file type | A file extension is on the destination tenant’s blocked list | Exclude file, rename extension, or request exception in tenant settings |
| Oversized file | A file exceeds the destination library’s per-file limit | Split, compress, or re-path to a library with a larger limit |
| API throttling risk | Predicted request volume in a phase exceeds safe throttle headroom | Schedule cutover in a window with low tenant activity, or stage in batches |
| Invalid character | An item has characters in a filename or field that are illegal on the destination | Character replacement rule in the migration profile |
| Path too long | The destination path (site URL + library + folder + filename) exceeds 400 characters | Rebase to a shorter destination path, or flatten folder depth |
| Unsupported feature | A source feature (e.g., Access Services list, InfoPath form binding) has no destination equivalent | Decide whether to skip, convert, or block |
| Configuration gap | A source site setting (e.g., multilingual variation, custom MUI labels) is not present on the destination | Provision missing config on destination before migration |
| Data integrity (not checked by Rehearsal) | A source artifact is corrupt or inconsistent (e.g., a lookup referencing a deleted list, a calculated column with a broken formula) | Clean up at source, or accept scrambling at destination |
1. Schema mismatch: the silent content-type collision
This breaks because two SharePoint environments evolved independently. The source tenant has a content type called Contract with fields { ContractValue, Region, Owner }. The destination tenant has its own Contract content type, possibly inherited from a managed solution, with fields { Value, Country, Approver }. Same name, same internal ID space, totally different schema.
On cutover day the symptom is a content-type creation error mid-run, or worse, items provisioned against the destination’s schema with all the field values silently dropped because the source field names do not exist on the destination type. Catching it requires comparing both ends’ content-type definitions field-by-field before the run, not after the first item write fails.
2. Permission risk: principals that do not exist on the other side
Cross-tenant migrations break here constantly. A document is shared with j.davies@oldcorp.com, but the destination tenant is newcorp.com and that user account never existed there. Internal migrations break here too: ex-employees, deleted security groups, expired guest accounts.
The cutover-day symptom is permission assignments silently skipped, leaving documents with narrower access than they had at source. Auditors notice this on Tuesday. Catching it means resolving every principal in source ACLs against the destination directory in advance and producing a list of unresolvable assignments before the run starts.
3. Blocked file type: the tenant policy nobody told you about
SharePoint Online has a tenant-level blocked file type list. Most tenants leave defaults (.exe, .bat) but security-conscious environments add .iso, .zip, .7z, or even .pst. The source tenant’s list is not the destination tenant’s list.
Symptom on cutover: every file with a blocked extension fails to upload, which can mean thousands of items in environments with archive ZIPs or PST exports. Catching it means reading the destination’s blocked list and pre-checking the source inventory.
4. Oversized file: per-library size limits
SharePoint libraries have a default per-file size limit (currently 250 GB for most plans, but admins can lower this per-library, and historical libraries often have much lower limits inherited from older site templates). Training videos, CAD files, lab data files routinely exceed library-specific caps.
On cutover the file upload fails with a generic 413 or a SharePoint-specific quota error, and the rest of the library may stall behind it depending on how the engine handles partial failures. Catching it means knowing each destination library’s real size cap, not the tenant default, and flagging every source file that exceeds it.
5. API throttling risk: the throttle that hits at hour 3
Microsoft Graph and SharePoint REST throttle aggressively. A migration that pushes 200,000 item writes in a tight window will hit a 429, then a longer 429, then potentially a tenant-wide cooldown that affects unrelated users. Throttling is not a hard error (the engine retries), but each retry compounds the runtime, and a planned 4-hour cutover can become 14 hours.
The symptom is a job that started fast and is now crawling, with the operator wondering whether to abort. Catching it means estimating request volume per phase against measured tenant headroom and warning before the run if a phase is likely to saturate.
6. Invalid character: filenames the destination will reject
SharePoint disallows specific characters in filenames and field values: #, %, &, *, :, <, >, ?, /, \, {, }, | (the exact list shifts depending on whether you came from on-premises). Files migrated from file shares or older SharePoint versions routinely carry these.
On cutover, items either fail outright or get auto-renamed in inconsistent ways depending on which API the engine uses, leaving downstream links broken. Catching it means scanning every filename against the destination’s rule set and flagging the rename target before the run, so the rename rule is approved and predictable.
7. Path too long: the 400-character ceiling
SharePoint enforces a 400-character limit on the full URL path: site URL + library + every folder segment + filename. Source paths that fit comfortably under the source URL can blow past the limit when rebased under a longer destination site name (contoso.sharepoint.com/sites/Finance-Hub-Migrated-2026-Q2/... is much longer than contoso.sharepoint.com/sites/Fin/...).
The cutover symptom is upload failures concentrated in deeply nested folders. Catching it requires computing the projected destination path for every source item before the run and flagging items that will exceed the limit so folder depth can be flattened or paths shortened.
8. Unsupported feature: legacy capabilities with no destination equivalent
SharePoint has accumulated and deprecated many features. Access Services lists, InfoPath form bindings, classic publishing infrastructure, custom site definitions, sandbox solutions. All of these can exist in a source environment with no clean destination equivalent in modern SharePoint Online.
On cutover, the engine either skips the feature silently (and the page renders broken at destination) or refuses to migrate the parent artifact entirely. Catching it means enumerating source feature dependencies and surfacing each unsupported feature with an explicit decision: skip, convert via a defined mapping, or block the migration until source is remediated.
9. Configuration gap: site settings the destination does not have
Variations, multilingual MUI labels, custom permission levels, audience targeting against deleted audiences, term store references that resolve only on source. These are settings that sit alongside content rather than inside it. They migrate poorly because the destination tenant has its own configuration story.
On cutover the content arrives but the site behaves differently: menus in the wrong language, audience-targeted web parts visible to everyone, term-driven navigation pointing nowhere. Catching it means comparing source site settings against destination provisioning state before the run and flagging every gap that will cause behavior drift.
10. Data integrity: the source was already broken
Lookups that reference a list someone deleted three years ago. Calculated columns with formulas referencing renamed fields. Workflow histories pointing at workflow definitions that no longer exist. Items in a state the source UI can no longer render. The migration engine inherits all of this.
The cutover symptom is unpredictable: items migrate but lookups resolve to nothing at destination, calculated fields show #ERROR, list views break. Catching it means actually exercising every lookup, formula, and reference during the pre-cutover scan instead of trusting that the source is internally consistent.
How to catch these before cutover
Most of the categories above are deterministic. Given the source data and the destination configuration, you can compute the answer in advance. You just have to look at the real source, item by item, instead of a sample.
MigrationFox Migration Rehearsal does that for SharePoint site migrations. It is a read-only pass over the source site (and, optionally, the destination site and your user mapping): it walks every document library, list, and page, compares content types with the destination, checks site-level permissions against the mapping, and checks the prerequisites for True History. Nothing is written to either tenant. It covers the categories that can be computed from the data: blocked file types, oversized files, paths over 400 characters, invalid characters, content-type mismatches, unmapped users, throttle risk, unsupported features, and configuration gaps. Source-side data integrity problems (broken lookups, bad formulas) still need a pilot run to surface.
The report has four headline outputs:
- Verdict: a single-line status: Ready to migrate, Proceed with caveats, or Do not migrate (at least one blocking issue that must be fixed first). Designed for change tickets, not spreadsheets.
- Runtime estimate: projected from the file, list item, and page counts using MigrationFox’s measured throughput, stated as a range.
- API request estimate: the expected number of Graph and SharePoint requests, so you know whether the run will push against tenant throttling and can pick the cutover window accordingly.
- Issue list grouped by category: every flagged item with its location and the typical fix attached.
Because the rehearsal reads every source item rather than a sample, the issues it reports are the ones the real migration would hit on those categories, found the week before instead of at 02:00 on cutover night.
Taking it to the change board
The rehearsal results live in the MigrationFox workspace, so the consultant and the client’s IT lead are looking at the same verdict, the same estimates, and the same issue list. Use the verdict and the issue list as the evidence on the change ticket, fix what is blocking, and re-run the rehearsal until it comes back clean before you schedule the real migration.
Related reading
Get started
Run a rehearsal on your next migration from the Governance workspace at app.migrationfox.com. Migration Rehearsal comes with the Tenant Suite or Consultant Pro; a single report pack does not include it. See pricing.