Diagnose and Resolve OneDrive Sync Issues on Windows

OneDrive for Business sync failures are among the most common end-user tickets in Microsoft 365 environments. Symptoms include files not uploading, the sync icon showing a red X or paused state, conflict files appearing with the user's name appended, or the client repeatedly asking for credentials.

Root causes typically fall into a few buckets:

• Authentication drift — expired tokens, conditional access changes, or a recent password reset
• File/path issues — unsupported characters, paths over 400 characters, locked files, or files larger than 250 GB
• Storage quota — user's OneDrive is full or nearing quota
• Client health — outdated OneDrive client, corrupted cache, or Known Folder Move misconfiguration
• Network / policy — proxy interference, tenant restrictions, or blocked endpoints

Run this recipe when a user reports "my OneDrive sync stopped," files aren't appearing on other devices, or you see the sync client stuck on "Processing changes" for an extended period.

After completing this recipe you will have:

• Identified the specific failure mode (auth, quota, file, client, or network)
• Collected diagnostic logs from the OneDrive client and tenant
• Restored sync functionality for the affected user
• Confirmed all pending files have uploaded and the client shows a green checkmark
• Documented the root cause for knowledge base / ticket closure

Warnings and Gotchas

• Do not delete the OneDrive cache folder (%LOCALAPPDATA%\Microsoft\OneDrive) without first confirming all local changes have been uploaded — unsynced edits will be lost.
• Resetting OneDrive (onedrive.exe /reset) is safe for synced files but will re-download the entire library, which can consume significant bandwidth for large libraries.
• Unlinking and relinking triggers a full re-scan. If Known Folder Move is enabled, verify Desktop/Documents/Pictures redirection is restored after relink.
• Conflict files (filename-Username.docx) must be reviewed manually — do not bulk-delete without user confirmation.
• Quota increases above the default 1 TB require a support ticket to Microsoft beyond 5 TB and are subject to license terms.
• Avoid running sync diagnostics during business hours on large libraries — the re-scan can saturate the user's connection.