sharepoint

SharePoint Sync Pending

Resolution Checklist

  • 1 Identify locked files or temporary Office file blocks
  • 2 Scan and rename long file paths and illegal characters
  • 3 Force restart and reset the OneDrive client
  • 4 Clear cached database files on Windows and macOS
  • 5 Disable Files-on-Demand to force full synchronization

SharePoint Sync Pending

This article provides a diagnostic checklist and troubleshooting guide to resolve SharePoint Sync Pending (such as files stuck in a “Sync Pending” or “Processing changes” loop, or local OneDrive directories showing persistent status wheels).

Root Causes / Meaning

A “Sync Pending” status indicates that the OneDrive client has queued a file for upload or download, but the transfer is blocked. Typical causes include:

  1. File Locks and Open Handles: An Office application (Word, Excel) or an external process has an active, exclusive lock on the file.
  2. Invalid Characters / File Name Rules: Files or folders containing forbidden characters (", *, :, <, >, ?, /, \, |) or names ending in spaces are blocked.
  3. Path Length Exceeded: The combined URL path (e.g., https://tenant.sharepoint.com/sites/site/library/folder/subfolder/file.docx) exceeds the 400-character SharePoint limit.
  4. Stuck Office Temp Files: Microsoft Office generates hidden owner files (~$filename.docx) while editing. If Office crashes, these files remain and block the folder sync.
  5. Sync Engine Database Corruption: The OneDrive client’s local SQLite database is out of sync and cannot process the queued file states.

Initial Checklist

Before proceeding to advanced fixes, perform these basic checks:

  1. Close All Office Apps: Ensure Word, Excel, and PowerPoint are completely closed to release any active file locks.
  2. Check for Hidden Files: Show hidden files in your folder explorer and look for file names starting with ~$.
  3. Verify File Size: Check if the pending file is extremely large (e.g., a virtual machine image or a raw database file), which might take a long time to process.

Platform-Specific Resolving Steps

Windows Users

Step 1: Force Kill and Reset the OneDrive Sync Client

Running the native reset command rebuilds the local database and clears stuck queues without deleting your offline files:

:: Force quit OneDrive
taskkill /f /im OneDrive.exe

:: Execute the built-in reset command
"%localappdata%\Microsoft\OneDrive\onedrive.exe" /reset

Note: Wait 2 minutes, then restart OneDrive if it does not launch automatically:

start "" "%localappdata%\Microsoft\OneDrive\OneDrive.exe"

Step 2: Identify Paths Exceeding SharePoint Limits (PowerShell)

Identify files exceeding the path length limit (400 characters) inside the local sync folder:

# Scan for file paths that exceed 260 characters locally (or 400 characters for SharePoint URLs)
Get-ChildItem -Path "$env:USERPROFILE\OneDrive - CloudProjectSoftware" -Recurse | 
Where-Object { $_.FullName.Length -gt 250 } | 
Select-Object Length, FullName

macOS Users

Step 1: Run the macOS Standalone OneDrive Reset Utility

Locate and run the built-in reset script via Terminal:

# Terminate OneDrive sync tasks
killall OneDrive 2>/dev/null

# Execute the built-in standalone reset script
/Applications/OneDrive.app/Contents/Resources/ResetOneDriveAppStandalone.command

Step 2: Search for Paths Exceeding Length Limits (Bash)

Scan the local OneDrive cache directory for exceptionally long file paths:

# Find any files in the OneDrive folder with paths longer than 250 characters
find ~/Library/CloudStorage -print | awk 'length($0) > 250'

Step 3: Delete Stuck Office Owner Temp Files

# Locate and remove temporary Office Lock files ($~ files) that are stuck
find ~/Library/CloudStorage -name "~\$*" -delete

Actionable Command Blocks

Completely Wipe Cache Directories (Windows)

If a reset fails, clear the local app data for a clean re-initialization:

:: Clear out local configuration caches (OneDrive will require signing in again)
taskkill /f /im OneDrive.exe
rmdir /s /q "%localappdata%\Microsoft\OneDrive\settings"
rmdir /s /q "%localappdata%\Microsoft\OneDrive\setup"

Completely Wipe Cache Directories (macOS)

# Wipe out OneDrive application support and preference plists
rm -rf ~/Library/Application\ Support/OneDrive
rm -rf ~/Library/Preferences/com.microsoft.OneDrive-mac.plist

Summary Checklist

  • Closed all Microsoft Office apps to release file locks.
  • Checked for and deleted temporary owner files (~$filename.docx).
  • Renamed files containing invalid characters (\, /, :, *, ?, ", <, >, |).
  • Verified file paths do not exceed the 400-character URL limit.
  • Executed the OneDrive reset command to rebuild the synchronization database.