How to fix OneDrive sync issues: a complete troubleshooting guide for Microsoft 365

OneDrive sync problems are one of the most common support tickets in any Microsoft 365 environment, and one of the least understood. The blue-and-white cloud icon in the notification area either shows a clean tick, or it doesn't, and when it doesn't, most users assume the fix is to restart the laptop and hope. Sometimes that works. More often the cause is one of a short list of known issues, most of which have a specific, documented fix.

This guide works through those causes in the order they're worth checking, from the quickest fix to the ones that mean the problem was never on the user's machine at all. It covers the Windows and Mac sync clients, the SharePoint document library sync button, and the point at which a recurring sync problem stops being a helpdesk ticket and starts being a tenant configuration question.

The most common causes, ranked by likelihood

Most OneDrive sync tickets Frontrow sees fall into one of these categories. Working through them roughly in this order, most to least common, resolves the majority of cases without needing a full client reset.

1. 1Sync is simply paused, manually, by a metered network setting, or by battery saver, and nobody noticed the icon changed
2. 2A file is open in another application, locked by a background process, or being scanned by antivirus, and won't release until it's closed
3. 3A file name, file type or path length falls outside what OneDrive and SharePoint support
4. 4OneDrive storage quota, or the local disk the OneDrive folder sits on, is full
5. 5The sync client itself has a corrupted local state and needs a restart or a full reset
6. 6The document library doesn't offer a working sync option because of a browser, permissions or site-configuration issue
7. 7An administrator has restricted sync at the tenant level, deliberately, and the fix isn't something the end user can apply at all

Restart the sync client before anything else

Before a full reset, try the lighter option. Right-click the OneDrive cloud icon in the Windows notification area (or the Mac menu bar), open Help & Settings, and check whether sync shows as paused. If it does, resume it. If it doesn't, close OneDrive from that same menu, then reopen it from the Start menu (Windows) or Applications folder (Mac). This alone resolves a meaningful share of tickets, because OneDrive's background sync engine occasionally stalls without any visible error, and closing and reopening the app clears the stall without touching any files.

Fully reset the OneDrive sync client

If a restart doesn't clear it, a full reset re-establishes the connection between the local OneDrive folder and the cloud without deleting or duplicating any files. It's the standard second step and is safe to run without warning a user, aside from a short window where the sync icon disappears from the notification area.

Windows

Press Windows key + R to open Run, then paste the following and press Enter:

The OneDrive icon will disappear from the notification area for up to a couple of minutes, then reappear and restart sync automatically. If it doesn't reappear within a few minutes, launch OneDrive manually from the Start menu, or run it directly from either C:\Program Files\Microsoft OneDrive\onedrive.exe or C:\Program Files (x86)\Microsoft OneDrive\onedrive.exe, depending on which is installed. If the device had selective sync configured (only some folders set to sync), that selection will need to be reapplied after the reset finishes. Note that the /reset switch doesn't work on the Microsoft Store version of the app; if that's what's installed, close and relaunch it instead.

Mac

On a Mac, click the OneDrive cloud icon in the menu bar, open Help & Settings, go to Preferences, select the Account tab, and choose Unlink this Mac. This disconnects sync without removing any files from the Mac or from the cloud. Sign back in with the same account to re-establish the connection. For a deeper reset, Microsoft ships a ResetOneDriveApp.command file inside the OneDrive application package; double-clicking it (or running it via Terminal) resets the client's local state before OneDrive is relaunched and signed in again.

Sync is paused, metered, or blocked by battery saver

OneDrive pauses itself automatically in a few situations that look identical to a fault from the user's side. It's worth checking these before assuming something is broken.

• Manually paused, someone clicked 'Pause syncing' from the notification icon, commonly for two hours or until tomorrow, and forgot
• Metered network, Windows lets OneDrive detect a metered Wi-Fi or mobile hotspot connection and pause large uploads to avoid data charges; this is a toggle in OneDrive settings under Network
• Battery saver, on a laptop running low on battery, OneDrive can pause background sync until the device is back on charge
• Focus assist or a VPN with split tunnelling misconfigured to exclude Microsoft 365 endpoints, which stops the sync client reaching the service at all

Storage full: OneDrive quota and local disk space

Two separate storage limits can stop a sync cold, and the error messages for each look similar. The first is the OneDrive account's cloud storage quota, whatever the user's Microsoft 365 licence allocates. Once that's reached, new files stop uploading and the sync icon shows a warning until space is freed or the quota is increased by an administrator. The second is local disk space on the device itself, if the OneDrive folder is set to keep files always available offline rather than using Files On-Demand, a laptop with a small solid-state drive can run out of room well before the cloud quota is touched. Checking free space on the local drive first takes thirty seconds and rules out one of the two causes immediately.

File names, path length and character limits

OneDrive and SharePoint both enforce naming and path rules inherited from a mix of the service itself and the operating systems syncing to it. A file that looks perfectly normal in an email attachment can fail to sync for reasons that aren't obvious from the error message alone.

• Invalid characters, the characters / \ < > : * " ? and | aren't allowed anywhere in a file or folder name, and leading or trailing spaces aren't permitted either
• Reserved names, Windows-reserved names such as CON, PRN, AUX, NUL and COM1 through COM9 and LPT1 through LPT9 can't be used as a file or folder name
• Total path length, the full decoded file path can't exceed 400 characters across OneDrive and SharePoint
• Per-segment length on synced devices, each individual folder or file name in the path is capped at 255 characters by the operating system, and on a synced PC or Mac the combined length of the local OneDrive folder path plus the file's relative path can't exceed 520 characters

In practice, the most common trigger is a deeply nested folder structure carried over from an old file server, where a handful of folder names were long descriptive sentences rather than short labels. Shortening the folder names near the top of the structure usually fixes every file underneath it in one pass, rather than renaming each affected file individually.

Blocked file types and files locked open elsewhere

A small number of file types are blocked from syncing by default, and an administrator can extend that block list to additional file types through the OneDrive admin centre for the organisation. Separately, a file that's open in another application, or locked by a background process such as antivirus scanning or an old, disconnected Office session, will show as sync pending until it's closed and the lock releases. This is especially common with large Excel workbooks left open overnight, or PST-style files that another process has a handle on.

No sync button on a SharePoint document library

This one is rarely a fault with the user's machine. A missing or non-functional sync option on a SharePoint document library usually comes down to one of the following: the browser being used doesn't support the sync prompt correctly, or has third-party cookies blocked, which the sync handshake depends on; the site owner or a tenant administrator has disabled syncing for that specific site or document library; the user only has view-level permissions on the library, which isn't sufficient to establish a sync connection; or the library is using the newer 'Add shortcut to OneDrive' option instead of the older Sync button, which some users don't recognise as the equivalent feature. Trying the same library from Microsoft Edge, and confirming the user's permission level on the site, resolves most of these without any change to the tenant.

Known Folder Move conflicts

Known Folder Move redirects a user's Desktop, Documents and Pictures folders into their OneDrive folder so they sync automatically. It's a useful default, but it conflicts in two common situations: when the local folder already contains files that differ from what's in the cloud copy of the same folder name, which can produce duplicate 'folder - PC name' copies while OneDrive works out which version is authoritative; and when another mechanism, most often a Group Policy folder redirection to a network share, is already redirecting the same folder, which the two systems fight over. Where Known Folder Move is being rolled out organisation-wide, checking for existing GPO-based folder redirection first avoids the conflict entirely rather than resolving it after the fact.

Files On-Demand versus always keep on this device

Files On-Demand shows every file and folder in File Explorer or Finder without downloading it until it's opened, which keeps local disk usage low and is the sensible default for most users. Setting a folder to 'Always keep on this device' downloads and keeps a full local copy, useful for a laptop that's frequently offline, but it removes the disk-space benefit of On-Demand entirely. A user who has marked their whole OneDrive as always-available on a small-disk laptop, then wonders why the drive is full and sync has stalled, is usually looking at a Files On-Demand setting rather than a fault.

When it's not the device: tenant and admin-level causes

If the same sync failure shows up across several users, or a user reports it worked fine on one device but not another, the cause is often deliberate tenant policy rather than a fault to fix. Microsoft 365 administrators can restrict OneDrive sync to domain-joined or Microsoft Intune-compliant devices only, which blocks sync on unmanaged personal machines by design, a control Frontrow recommends as part of standard tenant hardening. Conditional Access policies can independently block or limit access to OneDrive and SharePoint from devices that don't meet the organisation's compliance or location requirements, producing a sign-in or access error that looks like a sync fault but is actually the access control working as intended. Where either applies, the fix is a tenant policy conversation with IT or the organisation's Microsoft 365 partner, not a setting on the affected device.

It's also worth being clear about what OneDrive sync is not. Sync keeps a local folder matched to a cloud copy; it isn't a substitute for a proper backup and retention strategy, and a ransomware event or a mass accidental deletion can propagate through sync to the cloud copy just as fast as it hits the local one. That's a separate conversation to a sync fault, but it's one worth having at the same time, since most businesses that raise OneDrive sync tickets haven't separately checked whether their Microsoft 365 backup coverage is adequate.

When to stop troubleshooting and call the people who manage the tenant

A single user with a stuck file is a five-minute fix using the steps above. A pattern across several users, a sync failure that reappears within days of being reset, or any sync issue that traces back to Conditional Access, device compliance or a tenant-wide policy is a different problem, and it needs someone with visibility into the tenant configuration, not just the affected laptop. Recurring OneDrive sync tickets are also a reasonably reliable early indicator of a wider device compliance or Conditional Access gap that hasn't been reviewed in a while.