🔧 Recipe · Troubleshooting & Diagnostics

Diagnose and Resolve OneDrive Sync Issues on Windows

Systematic troubleshooting for stuck, paused, or broken OneDrive for Business sync clients

Complexity

Intermediate

Impact

troubleshooting + end-user-support + microsoft-365 + onedrive + productivity

Context

Why This Matters

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.

Expected Outcomes

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

Risks & Considerations

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.

Required Permissions

Permission	Why It's Needed
User.Read.All	Read user profile to confirm licensing and UPN
Directory.Read.All	Verify group membership and conditional access assignments
Reports.Read.All	Pull OneDrive usage and storage reports
Files.Read.All	Inspect the user's OneDrive drive metadata and quota
SharePoint Administrator role	Adjust per-user OneDrive storage quotas if needed

The fastest way to get this done: just ask Dex. Copy the prompt below and paste it into your Dex conversation.

For IT Admins

Paste into Dex Pro

{user} reports their OneDrive sync has stopped working. Diagnose the issue — check quota, licensing, recent sign-in failures, and drive health — then apply the appropriate fix (increase quota, reset client, or re-provision) and confirm sync is restored.

Try in Dex Pro

For End Users

How an employee would ask Dex for help

My OneDrive stopped syncing and my files aren't showing up on my other computer.

Try in Dex Playground

Manual Diagnosis via GUI

Step 1: Check the OneDrive client on the user's machine

Have the user click the OneDrive cloud icon in the system tray.
Review the activity center for error messages — note any red X, paused state, or "Sign in" prompt.
Click Settings (gear) → Settings → Account and confirm the correct work account is listed and shows an accurate storage quota.

Step 2: Run the built-in troubleshooter

On the user's Windows device, open Settings → System → Troubleshoot → Other troubleshooters.
Locate OneDrive and click Run.
If unavailable, use Help & Settings → View sync problems from the OneDrive tray icon.

Step 3: Verify tenant-side health in Microsoft 365 Admin Center

Sign in to admin.microsoft.com.
Navigate to Users → Active users → [select user] → OneDrive tab.
Review storage used vs. allocated. If at >99%, increase quota before proceeding.
Check Health → Service health for active OneDrive incidents.

Step 4: Reset the OneDrive client if needed

Close OneDrive: right-click the tray icon → Quit OneDrive.
Press Win+R and run: %localappdata%\Microsoft\OneDrive\onedrive.exe /reset
Wait 2 minutes. If OneDrive does not relaunch, run %localappdata%\Microsoft\OneDrive\onedrive.exe manually.
Sign the user back in and allow the library to re-index.

Step 5: Confirm resolution

Have the user create a small test file in their OneDrive folder.
Verify it appears in the web UI at onedrive.live.com within 1–2 minutes.
Confirm the tray icon shows a solid green checkmark.

Diagnostics via Microsoft Graph API

Use Graph to inspect the user's OneDrive state, quota, and recent activity without touching their device. This is useful for triage before scheduling a remote session.

1. Check drive quota and state

GET https://graph.microsoft.com/v1.0/users/{userPrincipalName}/drive

Response includes a quota object:

{
  "id": "b!abc123...",
  "driveType": "business",
  "quota": {
    "deleted": 1048576,
    "remaining": 536870912000,
    "state": "normal",
    "total": 1099511627776,
    "used": 562640755776
  }
}

Check quota.state — values of nearing, critical, or exceeded indicate quota is the cause.

2. Inspect recent drive activity

GET https://graph.microsoft.com/v1.0/users/{userPrincipalName}/drive/root/delta

An empty or stale delta response suggests the client isn't syncing changes back to the service.

3. Pull OneDrive usage report

GET https://graph.microsoft.com/v1.0/reports/getOneDriveUsageAccountDetail(period='D7')

4. Check for risky sign-ins blocking auth

GET https://graph.microsoft.com/v1.0/auditLogs/signIns?$filter=userPrincipalName eq '{upn}' and status/errorCode ne 0&$top=20

5. Increase quota if needed (SharePoint admin)

PATCH https://graph.microsoft.com/v1.0/users/{userPrincipalName}/drive

{
  "quota": { "total": 2199023255552 }
}

Note: direct quota PATCH is limited; use SharePoint PnP or Set-SPOSite for production quota changes.

PowerShell Troubleshooting

The script below automates the full diagnostic sweep: it checks licensing, quota, recent sign-in failures, and OneDrive provisioning state, then outputs a structured report you can attach to the ticket.

Prerequisites

Microsoft.Graph module (Install-Module Microsoft.Graph -Scope CurrentUser)
Microsoft.Online.SharePoint.PowerShell module for quota changes
Global Reader or User Administrator role minimum; SharePoint Administrator for quota adjustments

What it does

Authenticates to Microsoft Graph with the required scopes
Resolves the user and confirms they have a OneDrive license (SharePoint Online plan)
Fetches drive metadata and evaluates quota state
Queries recent failed sign-ins that could indicate auth issues
Outputs a colored summary and writes a JSON report to disk

Client-side reset

If the diagnostic indicates a client-side issue, run this on the user's machine:

Stop-Process -Name OneDrive -Force -ErrorAction SilentlyContinue
& "$env:LOCALAPPDATA\Microsoft\OneDrive\onedrive.exe" /reset
Start-Sleep -Seconds 120
& "$env:LOCALAPPDATA\Microsoft\OneDrive\onedrive.exe"

Next steps

More Troubleshooting & Diagnostics recipes

Browse the rest of this category in the Dex Cookbook.

Automate this with Dex Pro

Let the autonomous IT engineer run this task under your policies.

Start free

Point Dex at a tenant and try it for 30 days, no credit card.