Your OneDrive is not syncing because the sync engine has hit a blocking condition it cannot resolve on its own: a credential that expired, a file path or filename that violates Windows or SharePoint naming limits, a conflicting lock on a file, a metered-network policy, or a corrupted local sync database. The client reports most of these as a generic "sync pending" state rather than a specific error, which is why the status icon often looks fine while nothing moves. The actual cause is almost always visible in the OneDrive activity center or the Windows Event Viewer, not in the file itself.
OneDrive is not a single program but a stack: a per-user sync engine process, a cloud filter driver that creates placeholder files, and a backend that reconciles changes by version. A stall anywhere in that stack produces the same surface symptom.
The sync engine maintains a local database that records the state of every file. When you change a file, the engine calculates a SHA-1 hash of its content, compares it to the stored hash, and queues an upload if they differ. That hash comparison is why a file you "did not touch" can still upload: opening and saving a document in some applications rewrites metadata and changes the hash even when the visible text is identical.
The cloud filter driver is the component that makes files-on-demand work. It intercepts file reads and downloads content only when an application asks for it. If the driver is stopped, outdated, or blocked by security software, files can appear present but never hydrate, and uploads can queue indefinitely. This is the layer most consumer troubleshooting skips.
Reconciliation happens by version, not by timestamp alone. When the same file changes on two devices, OneDrive creates a conflict copy rather than silently overwriting. A conflict copy named with your device name is not a sync failure; it is the engine refusing to destroy data. Users frequently misread these as broken sync when the engine actually worked correctly.
The practical takeaway: diagnose by layer. Confirm the account is authenticated, confirm the path is legal, confirm the network policy permits the transfer, then confirm the local database is intact. Most stalls are resolved in that order.
Quantified context: the limits that actually break sync
The most common hard failure is the path length limit. On Windows, the traditional MAX_PATH limit is 260 characters for the full path including the drive letter, and OneDrive historically enforced a 400-character limit for the full path to a synced item. Exceeding either produces a file that simply never uploads, often without a clear message. A folder nested six or seven levels deep with long descriptive filenames reaches 260 characters faster than most people expect.
Filename rules are equally unforgiving. OneDrive blocks names containing the characters \ / : * ? " < > | and rejects names ending in a period or space. It also blocks a specific set of reserved names inherited from Windows, including CON, PRN, AUX, NUL, COM1 through COM9, and LPT1 through LPT9. A file named "report.docx " with a trailing space will fail on every attempt.
Individual file size limits differ by account type and are worth knowing before you blame the client. Personal OneDrive accounts support files up to 250 GB. Work and school accounts using SharePoint behind the scenes historically capped at 15 GB per file, later raised to 250 GB, but tenant administrators can lower it. If a large video stalls at a consistent point, check the tenant limit before reinstalling anything.
Storage quota is a blunt cause that presents as silent failure. When your account is full, uploads queue and downloads may still work, which makes the account look half-functional. The activity center shows the quota state, but many users never open it.
Free space on the local drive matters more than people assume. Files-on-demand needs room for the local database and for any file marked "always keep on this device." A drive with under a few gigabytes free can cause the database to fail writes and the engine to loop. The counterintuitive part: deleting local files to make room can make things worse if those files were the only local copies of cloud-only changes.
The sync state timeline: what each phase means
Sync is not instantaneous, and the delay between a change and its appearance on another device follows a predictable sequence. Understanding the phases tells you whether you are looking at a stall or normal latency.
| Phase | Typical duration | What the engine is doing | Signal you will see |
|---|---|---|---|
| Local detection | Seconds | Hash comparison of changed files | Activity icon shows "processing changes" |
| Queue build | Seconds to minutes | Batching uploads, checking policy | "Uploading X files" with a count |
| Transfer | Depends on file size and bandwidth | Sending content to the backend | Progress percentage per file |
| Server commit | Seconds | Version assignment, conflict check | "Sync pending" briefly, then clears |
| Propagation to other devices | Seconds to minutes | Other clients poll or receive push | No local signal; appears on device 2 |
| Conflict resolution | Minutes | Conflict copy creation if versions diverge | A file with your device name appended |
| Retry backoff | 1 to 30 minutes, escalating | Engine postpones a failing item | Item stuck at "sync pending" |
The retry backoff row is the one that confuses people most. When an item fails, the engine does not retry it immediately. It waits, and the wait grows with each consecutive failure. A file that failed once may sit for a minute; a file that failed five times may sit for half an hour. During that window the item looks stuck but the engine is deliberately pacing itself to avoid hammering a failing endpoint. The professional caveat: do not "fix" this by repeatedly restarting OneDrive, because each restart resets the queue and the backoff, which can extend the total time.
Edge cases that produce identical symptoms
Metered network detection is a frequent culprit on laptops. OneDrive pauses large uploads when Windows marks the connection as metered, which happens automatically on cellular connections and can happen on Wi-Fi you have configured that way. The sync icon shows a paused state, but users on a tethered phone often read it as broken. The threshold is not a fixed size; the client pauses transfers it deems large on metered links, so a folder of small documents may sail through while a single large archive stalls.
Files open in another application can block upload because the engine cannot get a read lock. This includes files open on another device, files locked by a backup tool, and files held by antivirus scanning. The lock is momentary in most cases, but a backup job that holds files for an hour will hold the queue with it.
Antivirus and endpoint protection software can block the cloud filter driver itself. Some suites intercept file system calls and do not properly pass through the reparse points that files-on-demand uses. The result is a client that appears to sync but never completes hydration or upload. This is more common in managed corporate environments, where security policy and sync policy are configured by different teams that do not coordinate.
Account and tenant policy is the invisible edge case. Conditional access policies can revoke the sync client's token while leaving the web session alive. Retention policies can move items to a preservation library that does not sync back. An administrator disabling the sync client for a device class produces a client that authenticates but refuses to transfer. None of these show a "wrong password" error.
A corrupted local sync database produces broad, non-specific failure: the engine starts, throws an error, and restarts in a loop. The database lives in a hidden per-user folder, and the standard repair is to reset the client, which rebuilds the database from scratch. That is safe for cloud data but re-downloads everything you had marked for local availability.
Misconceptions that send people down the wrong path
The first misconception is that the green checkmark means everything is synced. It means the last operation the engine attempted completed. Items queued behind a stalled item can sit unsynced while the icon stays green, because the engine does not change the global icon for queued-but-not-failed items. Trust the activity center's file list, not the tray icon.
The second is that reinstalling OneDrive fixes sync problems. Reinstalling replaces the client binaries but leaves the local database, the settings, and the account tokens in place. It fixes almost nothing that a reset does not fix faster. The exception is a genuinely corrupted installation, which is rare and usually shows a crash on launch rather than a sync stall.
The third is that "sync pending" means the server is down. Server outages do happen and they do stall everything, but they are far less common than the local causes above. The reliable check is the service health page for your tenant, not the client.
The fourth is that conflict copies are errors. They are the engine protecting you. Deleting them without comparing versions is how people lose the edits they actually wanted.
The fifth, and the most expensive in time, is that a bigger upload should be split into many small files to "help" sync. Splitting a large file into hundreds of small ones increases the per-file overhead (each file gets a hash, a queue entry, and a server round trip) and slows total transfer. The client handles large files well; the limit is the account's per-file cap, not the engine's stamina.
Practical actions with concrete thresholds
Work top-down through the stack, and stop at the first thing that is actually wrong.
Check authentication first. Open the OneDrive settings, look at the account pane, and confirm there is no "sign in" prompt and no red banner. If the token expired, re-authenticate before touching anything else. A re-auth takes under a minute and resolves a large share of "not syncing" reports. Check the activity center for the specific file and error. The file name and the error code matter more than the icon. Note whether the stalled item is a single file or the whole queue; a single item points to path, name, or lock problems, while a whole queue points to account, network, or database problems. Audit the path length and filename. Count characters from the drive letter to the extension. If the full path exceeds 260 characters, shorten folder names or move the item up a level. Remove trailing spaces, trailing periods, and reserved names. This step alone fixes most Windows sync stalls. Confirm the network is not metered. In Windows settings, check the connection's metered status. On a tethered connection, either mark it unmetered or wait for Wi-Fi. If the pause is deliberate, the client will resume on its own once the policy allows. Check free disk space and account quota. Aim for at least a few gigabytes free locally, and confirm the account is not at its storage limit. A full quota blocks uploads while leaving downloads working, which masks the cause. Reset the client if the database is suspect. The reset rebuilds the local database and re-establishes sync relationships. It does not delete cloud data. Budget time for re-downloading anything marked "always keep on this device." Escalate to the administrator if the device is managed and the above steps change nothing. Tenant policy, conditional access, and retention settings are configured server-side and cannot be fixed from the client.
Limitations and what this cannot tell you
No client-side diagnostic can see tenant-level policy, and no article can see your specific error code. The mechanisms above explain why sync stalls, but the resolution for any single machine depends on the actual error text in the activity center and, for managed devices, on the tenant configuration. If your organization manages the device, the fastest path is often a support ticket with the exact error code and the affected file path attached, because the administrator can see server-side policy and service health that you cannot.
Consumer OneDrive and work OneDrive are different products behind a similar interface, and their limits differ in ways that change over time. Treat the specific numbers here as of the date of writing and confirm current limits against Microsoft's documentation for your account type before making decisions about very large files or deep folder structures.
Nothing in this article is a diagnosis of your specific system. It is general educational information about how sync engines fail, not a support contract or a guarantee that any listed step will resolve a given machine's problem. For a managed device, bring the error code and path to your IT administrator; for a personal account with data you cannot lose, back up locally before resetting anything.