GOVERNANCE · April 15, 2026 · 13 min read
Insured SharePoint migrations: the dry-run that tells you what will break before it does
Everyone who has run SharePoint migrations at scale has the same bad memory. You plan the cutover for Saturday 22:00. At 02:00 you hit an issue nobody predicted — a content type with a site column that has the same internal name as a tenant-level field, or a folder path that crosses the 400-character URL limit the moment you rebase under a longer destination site, or a blocked file type the client was sure they did not use. The migration rolls back, or it limps forward with half the items failed, and Monday morning becomes a cleanup operation.
The root cause is almost always the same: the first time the migration tool exercises the real source data is during the real cutover. You discover the edge cases in production, with the timer running.
Migration Rehearsal exists to move that discovery forward in time. You run a full dry-run against the real source and a temporary destination, the engine executes every single phase of the real migration without writing to the live target, and the output is a report that tells you the three things you need to commit to the migration: what will break, how long it will take, and whether it is safe to proceed.
The sign-off workflow
The rehearsal is designed for the migration-lead-to-stakeholder relationship, not just the engineer. The pattern:
- Migration lead runs rehearsal. Picks source site, destination scope. Rehearsal runs. Takes anywhere from 8 minutes (small site) to 90 minutes (large site with thousands of items).
- Migration lead reviews report. Verdict pill at the top. Issue list below. Runtime prediction. API cost prediction.
- Report is presented to the client or change board. Either the printable PDF or a shared link. Readers see the verdict and the issue detail.
- Client signs off. In-product sign-off record, or out-of-band via the PDF attachment to a change ticket. The sign-off record locks the rehearsal version against the actual migration.
- Real migration runs. The same config that was rehearsed is the config that runs. Any drift between rehearsal and production (e.g., source content changed in the interim) is detected and flagged.
- Destination matches prediction. Because the rehearsal executed the same phases and made the same decisions, barring new source changes the real run lands exactly where the rehearsal said it would.
The practical value is in step 4. “Client signs off” is what turns a migration from a we-carry-all-the-risk project into a jointly-approved change. If something surfaces during the real run that was not in the rehearsal report, the conversation is specifically about what changed in source data since the rehearsal. If everything matches, the migration is uneventful, which is the correct outcome for a successful cutover.
What the rehearsal actually does
Mechanically the rehearsal re-uses every phase of the production migration path except the destination write. It:
- Enumerates the full source (lists, libraries, items, files, permissions, content types, site columns, views, pages)
- Runs the destination readiness check (schema conflicts, blocked file types, path length, permission target mapping)
- Simulates every write against an in-memory model of the destination state, including applied content types and field bindings
- Records an estimated HTTP request count per destination API (Graph
POST /sites/{id}/lists, SharePoint REST_api/web/lists/{id}/items, etc.) - Multiplies request counts by measured round-trip latency on the tenant to produce a runtime prediction
- Does not write a single byte to the real destination
Because the rehearsal is a real execution (just 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 10 issue categories
Every issue the rehearsal emits is tagged with one of ten category codes. Ten is not an arbitrary number; it is the enumeration of issue classes we have actually seen cause production rollbacks.
| 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 |
Each issue carries the site, list, item, and field context so you know exactly where it came from. Issues are grouped by category in the UI; you can drill into any category to see every matching item.
The verdict pill
At the top of the rehearsal report is a single-pill verdict. The logic:
- Ready to migrate — no issues in any blocking category. Warnings may exist but nothing that will cause a failure during cutover.
- Proceed with caveats — issues exist but all are in categories where the migration can continue with a known outcome (e.g., some files will be renamed due to
invalidCharacter, some permissions will be skipped due topermissionRisk). The migration lead and client need to acknowledge the caveats. - Do not migrate — at least one issue is in a hard-blocking category (
schemaMismatchthat will fail content-type creation,pathTooLongthat exceeds the absolute limit,unsupportedFeaturethat cannot be skipped). Fix these before the real run.
The verdict is intentionally simple. Clients do not want a spreadsheet; they want a green-yellow-red and a reason. The pill sits above the fold of the PDF report. The detail is below for anyone who wants to dig.
Runtime and API-cost prediction
Every rehearsal produces two numbers the client wants to know before signing off.
Runtime prediction is computed by tagging every simulated write with an expected latency drawn from the tenant’s measured round-trip time during the rehearsal itself. We distinguish seven latency classes (Graph metadata read, Graph list create, Graph item write, SP REST item write, large file upload, permissions write, page write) and sum across them. The prediction is stated as a range, because end-run variance from throttling and transient tenant load is real. Empirically the actual wall-clock time lands inside the range around 85% of the time.
API request-count prediction is a raw sum of every HTTP request the rehearsal recorded. This matters for two audiences: the client who wants to know if the migration will consume unusual tenant throttling headroom, and whoever is billing against a fixed Graph quota. A line that says “estimated 187,400 Graph requests, of which 142,000 are item writes” gives both.
How to use it
- Open
/governance/rehearsal. Configure the source site and destination target just as you would for a real migration. - Set any migration options you would set for production (permissions replay on/off, content type strategy, file-type filters).
- Click Start rehearsal. The rehearsal is queued and runs on the same worker pool as real migrations.
- When it finishes, open the report. Verdict pill at the top, issue categories below, runtime and API prediction in the header.
- Triage issues. Exact items are click-through to the source artefact for inspection.
- Fix anything in a blocking category. Re-run the rehearsal — re-runs are fast because the source enumeration is cached.
- Share the report URL or export the PDF. Record client sign-off.
- When it is time to cut over, convert the rehearsal into a production job with one click. The profile is locked to the signed-off version.
What changed since last quarter
The April 2026 rehearsal build added three things worth naming:
- Drift detection between rehearsal and production run. If source data changed materially between the rehearsal and the real migration, the production job pauses and asks for re-sign-off on the delta instead of silently overriding the old rehearsal contract.
- Per-category issue thresholds. A tenant admin can configure “auto-block if more than 50
invalidCharacterissues” so that large-scale issues never silently get the proceed-with-caveats verdict. - The PDF report is now brandable with your firm’s logo and colours. This turns the rehearsal from an internal tool into a client deliverable.
When rehearsal is not enough
Honest scope. The rehearsal is excellent at predicting issues that are deterministic functions of the source data — schema conflicts, path length, character rules, file-size limits. It is less excellent at predicting issues that depend on destination-side state that was not present at rehearsal time — for example, a content type that is added to the destination between rehearsal and cutover, or a tenant-level DLP rule change. The rehearsal report says this out loud: “Predictions assume destination state at {timestamp} is preserved at cutover.”
This is why the drift check exists. If anything on the destination side has meaningfully changed between rehearsal and real run, the job refuses to run silently.
Why the sign-off workflow changes the economics
If you have ever priced a fixed-fee SharePoint migration, you know the price is really “base work + contingency for surprises.” The contingency line is pure risk premium that the client pays and the delivery team absorbs. A well-run rehearsal shrinks the contingency to near zero because the surprises are surfaced in advance. The quote can be priced tighter. The client pays less. Both sides sleep better on cutover night.
“We do not price for surprises anymore. The rehearsal tells us what is in scope before we quote.” — consulting partner on a 14-site migration last month
Related reading
- SharePoint migration best practices
- Delta sync: how the second migration does not have to redo the first
- Cross-tenant SharePoint permissions without user-mapping hell
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.