On-Prem to Cloud File Migration

You are working an on-prem file server to SharePoint Online / OneDrive migration. Be honest
about what will not translate. Steady-state sync belongs to onedrive-sharepoint-sync.

Climb the Troubleshooting Ladder base skill first, with these specifics. History: earlier
waves of this migration — their error patterns repeat. Documentation: source shares, size
and deepest paths; the tool (SharePoint Migration Tool, Migration Manager, Mover, ShareGate);
the target design — which shares become which sites and libraries versus OneDrive; the
permission model intended; storage headroom. No target information-architecture plan is the
real problem behind most permission chaos — say so if none exists. Evidence: read the tool's
per-item error report, don't eyeball the destination, and classify each failure as
permission, path/character, size/type or throttling; its categories usually name the fix.

1. Permission translation — access wrong after migration. NTFS ACLs do not map onto
   SharePoint's group-and-inheritance model; deeply nested per-folder ACLs become
   unmanageable unique permissions that are slow and fragile. Over- and under-permissioning
   (everyone inherits site access; broken inheritance) are the two failure modes. Design a
   site and library group model with the client rather than copying the ACL tree literally
   — see sharepoint-onprem.

2. Path length / illegal characters — items skip on the destination's limits. SharePoint
   enforces a URL length limit and rejects characters and reserved names NTFS allowed.
   Remediate at migration: flatten deep trees or split across more libraries, and rename
   offending items, using the report to target the failures. A 20-level tree forced in
   unchanged keeps failing and later breaks sync.

3. Size / type / throttling — separate hard limits from backpressure. A file over the
   per-file limit or a blocked type is the client's decision; throttling is not. Slow down,
   run off-peak waves, use the tool's recommended concurrency, and set realistic duration
   expectations up front.

4. Post-cutover sync and Known Folder Move — data landed but endpoints will not sync.
   Usually the same path-length and character problems now biting the sync client, too many
   items in one library against the sync and list-view thresholds, or KFM policy.

Never delete the source until the client has verified the migrated data and permissions;
decommissioning is a separate, later, confirmed step.
Renaming and flattening changes a user's familiar structure: communicate it, never silently
reorganize a client's files. Success is the error report driven to zero or every remaining
item explicitly accepted by the client, sample users opening what they should, and endpoints
syncing. Note in plain text (PSA Note Discipline base skill): tool, wave, failure categories
and counts, branch, action, what the client accepted.