SharePoint document library sync lets users access files from File Explorer without switching to a browser. But if you enable sync without preparation, users often see sync errors, broken shortcuts, or missing files. The main cause is library structure and file path length that exceed Windows limits. This article provides a practical checklist to prepare your library before turning on sync, so the process works for everyone.
Key Takeaways: Library Sync Preparation Checklist
- Limit folder depth to 5 levels: Prevents file path length errors that stop sync from completing.
- Keep file names under 100 characters: Avoids sync failures caused by Windows path length limits.
- Remove unsupported characters from file names: Characters like : ” ? < > | cause sync to fail silently.
- Set library size below 300,000 items: Large libraries slow sync and can exceed the OneDrive sync app threshold.
- Verify user permissions: Users need at least Read access to sync; Contribute is required to upload files.
Why Library Structure Causes Sync Problems
SharePoint sync uses the OneDrive sync app on Windows and Mac. The app downloads files to the user’s local drive and keeps changes in sync. But the sync app has technical limits that the library must respect.
The main constraint is the Windows file path limit of 400 characters. When a file is synced, its full path includes the local sync folder path plus the SharePoint folder structure and file name. If this combined path exceeds 400 characters, the file fails to sync. Users see a red circle error in File Explorer.
Another constraint is the total number of items in the library. The OneDrive sync app can handle up to 300,000 files across all synced libraries. If a single library has more than 300,000 items, the sync app may stop processing new changes or show “Processing changes” indefinitely.
File name characters also matter. Windows forbids these characters in file names: : ” ? < > |. SharePoint allows them in browser view, but the sync app cannot create files with those characters locally. The sync app skips those files without warning the user.
Finally, user permissions affect sync. Sync works only if the user has at least Read access to the library. If permissions change after sync is enabled, the user may see stale files or get access denied errors.
Checklist to Prepare Your SharePoint Library for Sync
Follow these steps in order before enabling sync for any document library. Each step addresses one of the common failure points described above.
- Check folder depth and file path length
Open the library in SharePoint. Navigate to the deepest subfolder. Note the folder structure. The total path from library root to the deepest file must not exceed 5 levels. If it does, restructure folders to reduce depth. Use SharePoint admin center > Active sites > select your site > Document libraries to view the library path length for all items. - Rename files with long names
Use SharePoint > Library settings > More library settings > Per-location view settings to sort files by name length. Alternatively, export the library contents to Excel and check the LEN function on file names. Rename any file exceeding 100 characters. A safe maximum is 80 characters to leave room for local sync folder prefix. - Remove unsupported characters from file and folder names
Use SharePoint > Library settings > More library settings > Manage files which have no checked in version to locate files with invalid characters. The characters to remove are : ” ? < > |. Use the browser rename function to replace or remove these characters. Do this for folder names as well. - Reduce library item count below 300,000
Check the item count in SharePoint > Library settings > More library settings > Total number of items. If the count exceeds 200,000, plan to archive old files. Create a separate library named “Archive” and move files older than 12 months there. Use SharePoint > Library settings > Information management policy settings to automate file archiving. - Verify user permissions for the library
In SharePoint, select the library > Library settings > Permissions for this document library. Ensure that all users who need sync have at least Read permission. For users who need to upload files, assign Contribute permission. Use SharePoint admin center > Active sites > select your site > Site permissions to check group memberships. - Enable versioning and set a retention policy
In SharePoint > Library settings > Versioning settings, enable major versioning with a limit of 100 versions. This prevents storage bloat that slows sync. Also set a retention policy via Microsoft Purview compliance portal > Policies > Retention to auto-delete files after a set period. - Test sync with a small group of users
Create a test library with 50 files. Ask 2-3 users to sync it using the OneDrive sync app. Monitor for errors in the OneDrive sync icon > View sync problems. Fix any issues before enabling sync for the full library.
What to Do If Sync Still Has Problems After Preparation
OneDrive sync app shows “Processing changes” for more than 24 hours
This usually means the library has more than 300,000 items or there are file name conflicts. Open OneDrive settings > Account > Choose folders and stop syncing the library. Then re-sync only the top-level folders that users need. Alternatively, create multiple smaller libraries and sync each separately.
Users see “Access denied” error when trying to sync
The user has lost Read permission to the library. Check SharePoint > Library settings > Permissions for this document library. If the user is removed from the site members group, add them back. Also check if the library has unique permissions that override site permissions.
Synced files show a red circle with a white X
This error occurs when a file name contains unsupported characters or the path is too long. Use the OneDrive sync icon > View sync problems to see the exact file path. Rename the file in SharePoint to remove characters or shorten the path. The sync app will retry automatically within 15 minutes.
Sync stops after moving a folder to a new location
Moving folders in SharePoint can break the sync relationship. Users must stop syncing the library and re-sync it. In OneDrive settings > Account, select the library and click Stop sync. Then go to the library in SharePoint and click Sync again. All files will re-download.
| Item | Before Preparation | After Preparation |
|---|---|---|
| Folder depth | Up to 10 levels | 5 levels maximum |
| File name length | 200+ characters | 100 characters maximum |
| Unsupported characters | Present in file names | Removed from all names |
| Library item count | 500,000+ items | Under 300,000 items |
| User permissions | Mixed or unknown | Read or Contribute assigned |
After you complete the checklist, your library is ready for sync. Users can sync files from File Explorer without errors. The OneDrive sync app will handle changes reliably. For advanced control, use SharePoint admin center > Sync settings to limit sync to specific libraries or groups.