OneDrive sync purgatory: a 2026 troubleshooting guide

The original version of this post, written in 2019, is still floating around. The advice in it is mostly out of date now: the Groove client is gone, the cache directories have moved, and most of the PowerShell renaming is unnecessary because the modern OneDrive client handles invalid characters more gracefully. Here is the current playbook for the OneDrive sync issues we still see in 2026.

What changed since the old advice

Three things matter for context.

Groove is dead. The old standalone OneDrive for Business sync client (groove.exe, msosync.exe) was retired years ago. The current OneDrive client is one process, ships with Windows, and updates itself. Any 2019-vintage advice that mentions terminating Groove processes can be ignored.

Files On-Demand is the default. Files in OneDrive are not all downloaded locally by default. They show in File Explorer with a cloud icon and download on access. Most of the “file is missing” problems we see now are not sync issues at all. The user is offline or has restricted bandwidth, and the file has not downloaded yet.

Known Folder Move is in everyone’s tenant. Desktop, Documents, and Pictures get redirected to OneDrive automatically for users in many tenants. This causes one specific class of problem we will cover below.

The current limits

For libraries you sync, the realistic ceilings:

• 300,000 files per library is the documented cap. Performance starts degrading well before that. We tell clients to keep libraries under 100,000 if responsiveness matters.
• 400-character path length is the Windows limit when long paths are not enabled. Get-anywhere-near-it paths break sync.
• 15GB per file is the upload limit. Smaller for slower connections that time out before the upload finishes.

If you are seeing sync problems and any one of these is being approached, that is the problem. Fix it before troubleshooting anything else.

A current troubleshooting flow

When OneDrive is misbehaving, work in this order.

1. Confirm the user is actually online and signed in

Click the OneDrive icon in the system tray. If the icon shows a slash, the client is paused or offline. If it shows an exclamation, click through to see the specific issue. If it asks for sign-in, the user’s tokens have expired (most often because of a Conditional Access policy change) and they need to authenticate again.

2. Check the OneDrive client version

The client is supposed to auto-update but sometimes does not. Right-click the tray icon, choose Settings, About, and confirm the version. If it is more than a few months old, force an update via the OneDriveSetup.exe installer.

3. Look at the activity center for specific errors

Click the OneDrive icon, then the activity center. Sync errors are usually listed there with a specific cause: a file path is too long, a filename contains an illegal character, the file is open in another application, the file exceeds the size limit. Fix the file. The sync resumes.

4. Reset the client

If errors are vague or syncing is just stuck, reset OneDrive. From a Run dialog:

%localappdata%\Microsoft\OneDrive\onedrive.exe /reset

The icon disappears for a few minutes while the client rebuilds its local state. Files are not deleted. The reset clears the sync queue and rebuilds the connection. This solves a meaningful share of “stuck on syncing X of Y” problems.

5. Check Files On-Demand state for the affected file

Right-click the file in File Explorer. If it shows “Always keep on this device” as an option, the file is currently online-only. If a user complains about a file being slow to open or unavailable, this is often what they mean. They are not in sync purgatory. They are on a slow connection trying to download a file on demand.

6. For Known Folder Move conflicts

If a user moved their machine from local Documents to OneDrive Documents and now has files in two places, or if KFM is being applied by policy and the user is mid-migration, expect a few days of confusion. Use the OneDrive client’s “Stop backing up” and “Start backing up” options to control which folders are protected. Avoid moving files manually during the transition.

7. For SharePoint libraries

The advice for libraries you sync from SharePoint is the same as for personal OneDrive, with one addition: if a library has been recently moved or renamed, the sync relationship can break. The fix is to remove the sync (right-click the folder in File Explorer, choose Settings, Stop sync) and re-sync from the new SharePoint location.

When to escalate

If multiple users in a tenant are seeing the same sync issue at the same time, it is probably not a client problem. Check the Microsoft 365 Service Health dashboard for incidents on OneDrive or SharePoint. If the issue is service-wide, there is nothing to fix locally.

If a single user is stuck after going through the steps above, the cleanest path is usually to unlink the account, sign back in, and let the client rebuild. Files in the cloud are safe. The local copy resyncs from scratch.

The 2019 advice was correct for its era. The current era has fewer process names to terminate and fewer cache directories to clear, and most of the sync problems that used to require manual intervention are now handled by the client. The pattern that has not changed: fix the file or path that is breaking the sync, give the client a moment, and move on.