OneDrive sync client deep dive

The OneDrive sync client is the engine that turns OneDrive and SharePoint libraries into folders on your laptop. For most users it just works, but it's also the component behind a disproportionate share of Microsoft 365 support tickets — and knowing how it works is most of what you need when it doesn't.

How sync works

The sync client maintains, for each synced library, a local root (under %USERPROFILE%\OneDrive - YourCompany on Windows, or ~/OneDrive - YourCompany on macOS) plus a metadata database tracking the state of every item. Changes upload as soon as the network allows; remote changes come down at similar speed. When the metadata database and reality disagree — after a crash, an aggressive antivirus, or a disk-full event — you get the classic stuck-sync symptoms, which is why "reset the sync client" (onedrive.exe /reset on Windows) fixes so many cases: it rebuilds the database and re-scans, without re-downloading files that already match.

The client handles:

• A user's OneDrive for Business (synced once signed in).
• SharePoint libraries explicitly synced via the library's Sync button.
• "Add shortcut to OneDrive" — a library appears as a folder inside the user's OneDrive rather than as a separate sync root.
• The user's personal OneDrive, kept strictly separate from the business identity.

Office files get special treatment: Word, Excel, and PowerPoint documents in synced locations co-author through the Office apps' own service integration, with the sync client coordinating rather than blindly copying — which is why co-authoring works in a synced folder at all, and why non-Office file formats are the ones that produce conflict copies.

Files On-Demand

By default, files appear in the folder but aren't downloaded until opened. Icons indicate state: cloud (online-only), green check (locally available), filled green circle ("Always keep on this device"). This means a user can "sync" a multi-terabyte SharePoint library without filling a 256 GB SSD. Files On-Demand is implemented with the OS's cloud-files stack (Windows) and the File Provider framework (modern macOS), so ordinary applications open placeholder files transparently — the download happens on first read.

Two operational notes. First, keep Files On-Demand enabled by policy; users who force everything to "always keep on this device" recreate the disk-full problem the feature exists to solve. Second, remember that online-only files need connectivity — build "mark these folders as always available" into travel guidance for offline-heavy roles.

Sync vs "Add shortcut to OneDrive"

These two ways of getting a SharePoint library onto a device coexist awkwardly, and picking a lane matters:

• Shortcut follows the user across devices and the web/mobile experience, and lives inside the OneDrive root. It's Microsoft's recommended pattern for shared libraries, and the one they keep investing in.
• Sync creates a separate per-device root under the tenant name, doesn't follow the user, but can be pre-configured by administrators via policy so team libraries appear automatically on managed devices.

The pain arrives when the same library is both synced and shortcut, or when a user adds a shortcut inside a folder that's already synced — nested sync relationships are where the weird errors live. Pick one pattern per library, tell users which, and note that you can't have both on the same device for the same library.

Common pitfalls

• Long paths — the full local path (root + folders + filename) still breaks some applications past ~256 characters even where Windows itself copes. Deep folder trees migrated from file shares are the usual culprit; flatten them at the source.
• Filename characters — " * : < > ? / \ | remain illegal, and names like CON or trailing dots still bite. Migration tools rename; humans creating files on Macs find the gaps.
• Conflict copies — two devices editing the same non-Office file offline produce a duplicate with the device name appended. Co-author in Office formats where possible; for design files and databases, sync is the wrong collaboration tool entirely.
• Antivirus and backup agents scanning the OneDrive root can fight the sync engine — exclude the sync database paths per vendor guidance.
• The 300,000-item guideline — beyond roughly that many items across synced libraries, sync performance degrades seriously. Users syncing entire departmental archives "just in case" is the root cause; shortcuts plus Files On-Demand to targeted libraries is the cure.

Deployment: the settings that matter

For IT, the goal is that sync starts working on first sign-in with nothing to configure. Four policies, set through Intune's settings catalog (or Group Policy), get you there:

1. Silent account configuration — signs the sync client into the user's work account automatically on Entra-joined devices.
2. Known Folder Move — redirects Desktop, Documents, and Pictures into OneDrive, silently. This is your endpoint file-backup story; ransomware recovery and painless PC replacement both fall out of it.
3. Files On-Demand enabled — enforced, not optional.
4. Allow syncing only from your tenant — blocks personal-account sync on corporate devices if your data-governance posture requires it.

Add the storage sense / disk space policies to automatically dehydrate cold files, and monitor sync health in the OneDrive sync reports in the Apps admin center — it surfaces devices with errors before the users call.

Do this and the sync client fades into the background, which is exactly where a sync client belongs.