Smart Solutions
Need help?
  • 100% Free & MIT Licensed
  • No third-party data hosting
OneDriveTroubleshootingHow-toPath Length

OneDrive Sync Pending or Red X on a SharePoint Library: Causes and Fixes

8 min readBy Offered as a service by our team

You synced a SharePoint library and now some folders carry a red X, or the OneDrive icon sits on Processing changes or Sync pending and never finishes. The client rarely says why on the surface, but it does keep a list of exactly what failed. This guide starts there and works through the causes that account for most of these tickets, from the cheapest fix to the heaviest. For the wider list of SharePoint errors, see SharePoint error messages explained.

What the icons mean

  • Blue cloud: the file is online only and takes no space on your device.
  • Green check: the file is stored on your device.
  • Circular arrows: the file is syncing right now. If it stays on this for a very long time on one file, that file is the problem.
  • Red X: an error. OneDrive couldn't sync that item.
  • Paused: someone paused syncing, or the client paused it on battery saver or a metered connection.

Step 1: read the sync problems list

Click the OneDrive cloud in the system tray (Windows) or menu bar (Mac) and choose View sync problems. Each entry names the file and gives a reason. Don't guess before you've read it, because the cause is usually one of the next six. If the list is empty but the status never clears, jump to the pause, unlink and reset steps below.

Cause 1: the file or folder name isn't allowed

SharePoint and OneDrive refuse certain names. Per Microsoft's restrictions and limitations page:

  • Blocked characters: " * : < > ? / \ |
  • Reserved names: .lock, CON, PRN, AUX, NUL, COM0 to COM9, LPT0 to LPT9, desktop.ini and _vti_.
  • A name that starts with ~$ (the temporary lock files Office creates).
  • Leading or trailing spaces. These are easy to create when you paste a name.

Rename the file or folder to something clean and the error clears on its own. Files copied in from a file server are the usual source, because Windows file shares are more forgiving than SharePoint.

Cause 2: the local path is too long

OneDrive measures the path it would create on your disk: your OneDrive folder, the library's sync folder name, and the path inside the library. When that passes 260 characters, files stop syncing. This is the most common cause on libraries with deep folders and long descriptive names. We cover the cause and fix in fixing the OneDrive path-too-long error and the 260-character limit that breaks shortcuts. For finding every offender at once rather than file by file, use the free Smart Path Length web part.

Cause 3: the file is open or locked

A file that is open in Word, Excel or another app, or locked by a person editing it elsewhere, can stall while OneDrive waits to read it. Close it everywhere, including on a colleague's machine if they have it open, and give the client a minute. Files that start with ~$ are the temporary copies Office writes while a document is open. They should disappear on close. If one is stuck, close Office fully and delete it.

Cause 4: you don't have permission to change the file

If you only have Read access to the library, anything you change locally can't upload and shows as an error. This often appears after a site owner changes permissions, or when someone syncs a library they only have Visitor access to. Check what you actually have on the site and ask the owner for Edit if you need it. See SharePoint permission levels explained for what Edit and Read allow, and how to see who has access to a site if you are the one sorting it out.

Cause 5: storage is full

Uploads fail when the destination is out of space. That can be your own OneDrive, or the SharePoint tenant storage for the site. If the library is on a site that has hit its quota, writes to it stop for everyone. Check what to do when SharePoint storage is exceeded, and use Smart Storage Analyzer to see where the space went.

Cause 6: too many items

The client slows down as the number of synced items grows, and that is a common reason for a sync that sits on Processing changes. Microsoft recommends syncing no more than 300,000 items across your cloud storage for optimal performance, and says performance issues can occur above that even if you don't sync every item. Microsoft also describes a public preview that supports up to 1,000,000 items per sync instance on Windows and macOS, with hardware and configuration requirements. The simple fix is to sync only the folders you need rather than whole libraries. Add shortcuts to the specific subfolders you work in.

Cause 7: the client itself is stuck

If the problems list is empty, or you've fixed every file and the status still doesn't clear, the sync relationship may be out of step. Work through these in order and stop as soon as it syncs:

  1. Pause and resume. Right-click the OneDrive icon, choose Pause syncing, then Resume syncing. This makes the client re-check its queue.
  2. Stop and re-sync the library. In OneDrive settings, open Account and choose Stop sync on the library. Before you do, move any files that exist only on your machine somewhere safe. Then open the library in SharePoint and choose Sync.
  3. Reset OneDrive. Press Windows+R and run %localappdata%\Microsoft\OneDrive\onedrive.exe /reset. If Windows can't find it, the same onedrive.exe is in C:\Program Files\Microsoft OneDrive. Start OneDrive from the Start menu if it doesn't relaunch on its own.

A reset doesn't delete your files. It disconnects the sync relationships and triggers a full resync, so expect it to take time on a large library, and re-select any folders you had chosen to sync. Treat it as the last step, not the first. If the problem returns after a reset, the cause is one of the six above.

Prevent it before you roll a library out

Most sync tickets are visible in advance. Before you ask a team to sync a library or add a shortcut, check three things:

  • Path length: run Smart Path Length and fix anything near 260 characters.
  • Names: clean up blocked characters, reserved names and stray spaces, especially in content that came from a file server.
  • Size and permissions: confirm the library isn't huge, and that the people syncing it have Edit, not just Read. A permissions report for one user answers that fast.

Related

Free · MIT license · no sign-up

Get your first result in about 10 minutes

Visual permissions audit + Excel export. No PowerShell. Free, MIT licensed, no sign-up.

  1. Download the .sppkg package from the latest release.
  2. Upload it to your tenant App Catalog.
  3. Add the web part to a SharePoint page.
Install guide
Download the latest releaseView on GitHub
Email me when a new release ships
Get notified when SharePoint Smart Permissions updates

No marketing spam. One short email when a new release ships. You can unsubscribe anytime.

Frequently asked questions

What does the red X on a OneDrive or SharePoint folder mean?

OneDrive couldn't sync one or more files in that folder. Open View sync problems from the tray icon to see which files and why, then fix the cause named there, such as an invalid name, a long path, a locked file or missing permission.

Why is OneDrive stuck on 'sync pending' or 'processing changes'?

The client is working through a large queue, is blocked by a file it can't process, or is syncing a library with a very large number of items. Check the problems list, pause and resume, and sync fewer folders. Microsoft recommends no more than 300,000 items across your cloud storage.

Will resetting OneDrive delete my SharePoint files?

No. Files in SharePoint stay where they are, and local files aren't deleted by a reset. OneDrive does a full resync afterward, which can take a while on a big library, and you may need to reapply selective-sync folder choices.

Why do some files sync and others show a red X in the same library?

Sync errors are per file. A few files with an invalid character, a path over 260 characters, an open lock or a name Microsoft reserves fail while the rest sync normally.

Can a read-only library cause sync errors?

Yes. If you only have Read permission, any change you make locally can't upload, so it shows as an error. Ask the site owner for Edit access, or move your local changes out of the synced folder.

How do I find every file that will fail to sync before I roll a library out to a team?

Check names and path lengths across the library before people sync it. The free Smart Path Length web part scans every library for paths that would pass the local limit and exports a shortlist to Excel.

Was this page helpful?

One click. No form, no email address.

Missing something in SharePoint Smart Permissions? Feature requests and bug reports go straight to the developer on GitHub — no account needed to read, free account to post.

Request a feature

Related tool

SharePoint Smart Permissions

Visual permissions audit + Excel export. No PowerShell. Free, MIT licensed, no sign-up.

Need expert hands on deck?

Let our team plan and run your SharePoint migration

Full-service file and metadata migrations across sites, tenants, or from on-premises to SharePoint Online, from planning and test runs to verification and cutover.

About the author

Sean Regan

SharePoint & Microsoft 365 consultant with 20+ years of hands-on experience building SPFx web parts, migration tooling and tenant-grade automation. Maintainer of the open-source SharePoint Smart Solutions suite.