GOVERNANCE · April 15, 2026 · 13 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.
After 10,000+ SharePoint migrations, ten failure categories cover almost every 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
Each of these has a category code that shows up in scan output. 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.
| Code | What it means | Typical fix |
|---|---|---|
schemaMismatch | 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 |
permissionRisk | 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 |
blockedFileType | A file extension is on the destination tenant’s blocked list | Exclude file, rename extension, or request exception in tenant settings |
oversizedFile | A file exceeds the destination library’s per-file limit | Split, compress, or re-path to a library with a larger limit |
apiThrottleRisk | Predicted request volume in a phase exceeds safe throttle headroom | Schedule cutover in a window with low tenant activity, or stage in batches |
invalidCharacter | An item has characters in a filename or field that are illegal on the destination | Character replacement rule in the migration profile |
pathTooLong | The destination path (site URL + library + folder + filename) exceeds 400 characters | Rebase to a shorter destination path, or flatten folder depth |
unsupportedFeature | A source feature (e.g., Access Services list, InfoPath form binding) has no destination equivalent | Decide whether to skip, convert, or block |
configurationGap | A source site setting (e.g., multilingual variation, custom MUI labels) is not present on the destination | Provision missing config on destination before migration |
dataIntegrity | A source artefact 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. schemaMismatch — 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. permissionRisk — 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. blockedFileType — 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. oversizedFile — 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. apiThrottleRisk — 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. invalidCharacter — 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. pathTooLong — 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. unsupportedFeature — 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 artefact 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. configurationGap — 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. dataIntegrity — 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
Every category above is deterministic. Given the source data and the destination configuration, you can compute the answer in advance — you just have to actually exercise the migration path against the real source.
MigrationFox Migration Rehearsal runs that exercise. It executes a full dry-run against the real source and a temporary destination model, walking every phase of the production migration path without writing to the live target. The output is a report covering all ten categories, with the same context (site, list, item, field) that the production engine would log.
The report has four headline outputs:
- Verdict pill — a single-line green/yellow/red status: Ready to migrate (no issues in any blocking category), Proceed with caveats (issues exist but the migration can continue with known outcomes), or Do not migrate (at least one issue in a hard-blocking category that must be fixed first). Designed for change tickets, not spreadsheets.
- Runtime prediction — computed by tagging every simulated write with an expected latency drawn from the tenant’s measured round-trip time during the rehearsal itself, across seven latency classes (Graph metadata read, Graph list create, Graph item write, SP REST item write, large file upload, permissions write, page write). Stated as a range; actual wall-clock lands inside the range about 85% of the time.
- API request-count forecast — a raw sum of every HTTP request the rehearsal recorded, broken down by API surface. Tells the client whether the migration will consume unusual tenant throttling headroom and gives anyone billing against a fixed Graph quota a real number to plan against.
- Issue list grouped by category — every flagged item, click-through to the source artefact, with the typical fix attached.
Because the rehearsal is a real execution with the writes short-circuited, the issue detection is real — no static linting, no rule-based guessing. If the production migration path would encounter a problem, the rehearsal encounters the same problem.
The client-signable report
The rehearsal output is a PDF report (and a shareable link) designed to attach to a change ticket. The verdict pill sits above the fold, with issue detail and predictions below for anyone who wants to dig. The PDF is brandable with your firm’s logo and colours, which turns the rehearsal from an internal tool into a client deliverable. Sign-off is recorded in-product, and the signed-off rehearsal version locks against the production run — if source data changes materially between rehearsal and cutover, the production job pauses and asks for re-sign-off on the delta instead of silently overriding the contract.
Related reading
Get started
Run a rehearsal on your next migration at app.migrationfox.com/register. Rehearsals are included on every workspace; sign-off and branded reports are in the Professional tier and up.