How sync actually works
The OneDrive client syncs personal OneDrive AND any SharePoint/Teams library the user chooses to sync. It tracks changes with a delta protocol — only what changed moves, not whole files — and reflects both directions continuously.
Files On-Demand is the piece that makes terabytes fit on a laptop. Files appear in Explorer/Finder as placeholders (reparse points on Windows) that occupy metadata, not full content. Their state:
| Icon state | Meaning |
|---|---|
| Cloud | Online-only — content not on disk; opening it downloads (hydrates) it |
| Green tick (outline) | Locally available — downloaded on use, evictable to reclaim space |
| Green tick (solid) | Always keep on this device — pinned, offline-guaranteed |
Hydration on first open is why "the file took ages to open" happens on a slow link, and why offline access to an online-only file fails on a plane.
The failure modes (the actual support queue)
- Sync conflicts. Two devices edit the same file while offline → OneDrive keeps both and creates a "…-Copy" / "conflicted copy" file. No data lost, but users panic and the wrong copy gets kept. Co-authoring in Office avoids this; raw file edits don't.
- Path length. The full path has a limit (historically ~400 characters). Deeply nested synced libraries hit it and files silently fail to sync — the classic "some files won't sync" ticket.
- Invalid names / blocked types. Leading/trailing spaces, reserved names, and certain characters block sync; some file types (e.g. .pst, or org-blocked extensions) are excluded.
- Storage-full. Full local disk stops hydration; full OneDrive quota stops upload — both present as "stuck" sync.
- Too many items. Very large synced libraries (guidance sits around the ~300k item mark before performance degrades) make the client sluggish or unstable — a reason to sync a subfolder, not a whole 5-million-item site.
- Office upload cache corruption — a stuck Office file often clears only by
resetting the client (
onedrive.exe /reset).
The admin levers
Sync is governed by tenant + policy settings: Set-SPOTenant flags like
AllowKnownFolderMove, and ADMX/Intune policies to restrict sync to
domain-joined/managed devices (AllowTenantList by tenant ID), block specific
file extensions, and limit which libraries can be synced. Unmanaged devices can be
blocked from sync entirely (Conditional Access concept).
What to watch (proofs)
- Client health at scale: OneDrive sync health dashboard (Apps admin center) — devices with sync errors, versions, and error categories across the estate.
- Managed-device restriction:
Get-SPOTenantSyncClientRestriction— is sync confined to the allowed tenant/device list, or open to any BYOD machine? - Local diagnosis: the sync client's Activity Centre and
%localappdata%\ Microsoft\OneDrive\logs— the per-device truth for a stuck-sync ticket. - Quota/disk: the user's OneDrive usage vs quota and free local disk — the two full-tank causes of "stuck".