How to Fix ‘iCloud Drive Not Syncing’ on Mac

Saving files to your desktop or documents folder on macOS only for changes to fail to sync across your iPhone, iPad, or other Macs disrupts daily productivity. In macOS, iCloud Drive synchronisation is managed by a background system daemon called bird, which monitors filesystem change notifications via the FSEvents framework. When local SQLite cache locks occur, system network daemons stall, or APFS extended attributes become desynchronised, iCloud Drive enters a paused or stalled state. This comprehensive guide walks you through terminating hung sync processes, forcing metadata refreshes, and resolving iCloud Drive sync failures without risking data loss.

Why Does iCloud Drive Stop Syncing on macOS?

Cloud synchronization across APFS and Apple servers relies on several interconnected system services:

• Locked Bird Process: The bird daemon hanging on an open file handle, causing pending upload queues to freeze.
• Corrupted CloudDocs Metadata Database: Damaged index files in the local ~/Library/Application Support/CloudDocs directory.
• Low Local Disk Space: When free storage on your Mac drops below 5-10 GB, macOS automatically pauses iCloud background sync to preserve drive integrity.
• Optimise Mac Storage Conflicts: Aggressive cloud offloading causing download loops for frequently accessed files.
• Apple System Status Outages: Temporary server-side maintenance on Apple iCloud Drive or CloudKit endpoints.

Method 1: Force Restart the iCloud ‘bird’ Daemon

Killing the hung bird process forces macOS to restart the iCloud Drive synchronisation engine and re-evaluate pending file queues.

1. Open Terminal via Spotlight (Cmd + Space, type Terminal, and press Enter).
2. Enter the following command and press Enter:

   killall bird

3. Wait 10 seconds. The operating system’s launchd daemon will automatically relaunch bird with fresh memory handles.
4. Open Finder and observe whether the small pie-chart progress icon next to iCloud Drive begins moving.

Method 2: Check Local Free Disk Space

iCloud Drive requires adequate local caching space to stage uploads and process changes.

1. Click the Apple menu () in the top-left corner and select System Settings.
2. Navigate to General > Storage.
3. Ensure that your Mac has at least 15 GB of available storage space.
4. If space is critically low, delete temporary files or empty the macOS Trash to allow iCloud daemons to resume background indexing.

Method 3: Reset the Local CloudDocs Sync Cache

If the local SQLite database that indexes your files has become corrupt, rebuilding it forces macOS to re-scan the cloud state.

1. In Terminal, paste the following command to remove the cached CloudDocs session:

   rm -rf ~/Library/Application\ Support/CloudDocs/session/db

2. Next, restart the bird process again:

   killall bird

3. Allow macOS several minutes to rebuild the database schema and re-verify checksums with Apple servers.

Method 4: Toggle iCloud Drive in System Settings

Refreshing your Apple Account cloud settings re-establishes secure SSL authentication tokens.

1. Open System Settings and click your Apple Account profile name at the top.
2. Select iCloud > iCloud Drive.
3. Turn off the toggle for Sync this Mac.
4. When prompted whether to keep a local copy of your files, select Keep a Copy to prevent unnecessary file re-downloads.
5. Wait 30 seconds, then toggle Sync this Mac back on.
6. Ensure that Desktop & Documents Folders is correctly toggled on if you store synced files in those locations.

Method 5: Check File Names for Unsupported Characters

Certain special characters or trailing spaces prevent POSIX file systems from transmitting paths to remote cloud storage:

• Inspect pending files for characters like :, /, or leading/trailing spaces.
• Ensure no single file exceeds the 50 GB iCloud upload limit.
• If a specific file displays a cloud with an exclamation mark, move it to a local folder outside iCloud, rename it with standard alphanumeric characters, and move it back.