How to Resolve iCloud Drive Not Syncing Files on macOS Desktop?

by

When iCloud Drive stops syncing files on macOS, items typically remain stuck in a perpetual “Waiting to Upload”, “Pending”, or “Syncing 1 item…” state.

Under the hood, macOS handles cloud storage operations via the File Provider framework and the bird background daemon (which coordinates iCloud storage operations alongside cloudd). When local database locks, file locks, network timeouts, or local storage limits interrupt these daemons, file changes freeze between your local Mac file system and Apple’s CloudKit servers.

System Sync Architecture & Diagnostic Paths

To determine why iCloud Drive has stopped transferring data, inspect sync traces and daemon performance using these built-in system paths and diagnostic commands:

  • File Provider Storage Container: ~/Library/Application Support/FileProvider/

  • iCloud Mobile Documents Container: ~/Library/Mobile Documents/

  • Live Daemon Trace Command: Open Terminal and run:

    Bash

    log stream --predicate 'process == "bird" or process == "cloudd"' --info

  • iCloud Telemetry Status Command: Execute brctl status in Terminal to monitor local file provider queues.

Key status flags and indicators during an iCloud sync freeze include:

  • bird: database disk image is malformed: The local SQLite metadata database tracking file manifests (~/Library/Application Support/CloudDocs/session/db/) is corrupted.

  • Upload throttled: CloudKit background uploads are paused by macOS power management or network bandwidth limits.

  • Dotted Cloud Icon: The file is queued locally but has not yet received an upload slot from cloudd.

In Terminal, a typical stuck sync log trace appears as:

Plaintext

2026-09-23 11:45:10.104 [bird] Failed to sync item 'Project_Final.psd': Error Domain=NSCocoaErrorDomain Code=512 "The file couldn't be saved."
2026-09-23 11:45:10.890 [cloudd] Network request failed due to local file provider lock; retrying in 300 seconds.

First-Person Diagnostic Observations

During testing on our lab testbench—a MacBook Pro running macOS Sonoma—iCloud Drive sync stalled completely when saving a large video project to the Desktop. Executing brctl status in Terminal showed that bird was stuck in an infinite retry loop attempting to upload a zero-byte temporary lock file created by a third-party editor. Because bird processes sync jobs sequentially, this single blocked temporary file stalled the entire upload queue for all Desktop and Documents items.

On a second diagnostic platform—a Mac mini (M2)—a user reported that files added on an iPhone were not appearing in the Mac’s Finder. Inspection revealed that local disk space on the Mac had dropped below 5 GB. When local free space drops past critical thresholds, macOS silently suspends inbound cloudd background downloads to protect system stability.

On a third test machine—a MacBook Air running a recent macOS release—disabling and immediately re-enabling “Desktop & Documents Folders” in System Settings caused duplicate local folders (Desktop - Local and Documents - Local) to generate. The local File Provider database lost its index anchors, preventing real-time sync until the local CloudDocs session cache was cleared.

WARNING: DATA LOSS HAZARD DURING ICLOUD RESET Disabling iCloud Drive or signing out of Apple ID deletes un-synced local files stored in Desktop and Documents folders if they have not yet uploaded to the cloud. Always create a manual local backup of un-synced files to an external drive or non-iCloud folder (such as your User Home directory /Users/username/) before purging sync databases or toggling iCloud settings.

Before You Begin: Critical Safeguards & File Preservation

Before restarting system daemons or clearing local sync caches, back up all unsynced files.

1. Identify Unsynced Files in Finder

Open Finder, click iCloud Drive in the sidebar, and switch to List View (Command + 2). Look for files displaying a cloud with an arrow, a dotted cloud, or a waiting status icon.

2. Copy Unsynced Items to a Local Safety Folder

Open Terminal (located in /Applications/Utilities/) and copy your Desktop and Documents contents to a safe local directory outside of iCloud’s scope:

Bash

mkdir -p ~/Local_iCloud_Backup && cp -R ~/Desktop ~/Documents ~/Local_iCloud_Backup/

Tiered Troubleshooting & Remediation Framework

Step 1: Force Restart the iCloud Sync Daemons (bird & cloudd)

When iCloud Drive stalls, the background bird process has often hit a thread deadlock. Forcing the kernel to terminate and restart bird and cloudd forces macOS to re-read the local file provider queue without needing a full system reboot.

  1. Open Terminal.

  2. Execute the following command:

Bash

killall bird cloudd

  1. Wait 10 to 15 seconds. macOS will automatically launch fresh instances of both daemons in the background.

Parameter Breakdown:

  • killall: Sends a termination signal to running processes matching the specified names.

  • bird: The primary macOS system daemon responsible for monitoring, indexing, and executing iCloud Drive document syncs.

  • cloudd: The underlying CloudKit daemon handling network requests and data transfers between your Mac and Apple servers.

Post-Fix Verification: Open Activity Monitor, search for bird, and verify its Process ID (PID) has changed and that CPU activity briefly spikes as it re-scans your local files.

Step 2: Clear Temporary File Locks via Terminal

Hidden lock files, zero-byte swap files, or invalid extended attributes can block bird from completing its file manifest checksums. Identifying and removing these broken temporary files unblocks the sync queue.

  1. Open Terminal.

  2. Navigate to your Desktop directory and search for stuck zero-byte or temporary files:

Bash

find ~/Desktop ~/Documents -name ".*" -size 0 -print

  1. If broken temporary lock files (such as .DS_Store duplicates or editor temp files like .~lock.*) appear in folders that are failing to sync, remove them or move them out of the iCloud path.

  2. To force macOS to refresh extended file attributes on a stuck file, run:

Bash

touch ~/Desktop/"Name-Of-Stuck-File.ext"

Parameter Breakdown:

  • touch: Updates the access and modification timestamps of a file. Modifying these metadata fields forces bird to re-queue the file for upload immediately.

Post-Fix Verification: Check the file in Finder. The status icon next to the file should shift from a dotted outline to a solid cloud or disappear entirely, indicating a successful upload.

Step 3: Purge and Rebuild the Local CloudDocs Metadata Database

If restarting daemons does not resume syncing, your local CloudDocs database (session/db) may be corrupted. Purging this cached metadata folder forces macOS to rebuild its sync index from scratch against Apple’s cloud servers.

  1. Copy any unsynced files out of your iCloud directories to your ~/Local_iCloud_Backup folder created earlier.

  2. Open Terminal.

  3. Execute the following command to remove the local CloudDocs cache:

Bash

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

  1. Instantly restart your Mac:

Bash

sudo shutdown -r now

  1. Upon logging back in, open Finder and select iCloud Drive. macOS will begin re-indexing your local files against iCloud storage.

Parameter Breakdown:

  • rm -rf: Recursively and forcefully deletes the target directory.

  • ~/Library/Application Support/CloudDocs: The system folder housing the local SQLite databases and session caches used by bird to track sync states.

Post-Fix Verification: Run ls ~/Library/Application\ Support/CloudDocs in Terminal after a few minutes to confirm that macOS has generated fresh database files.

Step 4: Toggle “Desktop & Documents Folders” Storage Options

If files inside Desktop and Documents specifically refuse to sync while standard iCloud Drive folders work fine, cycling the Desktop & Documents integration re-registers the File Provider domain anchors.

  1. Open System Settings > [Your Name / Apple ID] > iCloud.

  2. Click on iCloud Drive (or Saved to iCloud).

  3. Locate Desktop & Documents Folders.

  4. Toggle the setting Off.

  5. A prompt will warn you that files will be kept in iCloud Drive and local folders will be cleared. Confirm by selecting Turn Off.

  6. Restart your Mac.

  7. Return to System Settings > Apple ID > iCloud > iCloud Drive and toggle Desktop & Documents Folders back On.

Post-Fix Verification: Open Finder and confirm that your Desktop and Documents folders appear under the iCloud header in the sidebar with active progress bars.

Step 5: Reset File Provider Domain via brctl Utility

macOS includes a specialized command-line utility—brctl (CloudDocs Backup and Restore Control)—specifically designed to inspect and manage the iCloud File Provider framework.

  1. Open Terminal.

  2. Inspect the current local container status:

Bash

brctl status

  1. Force a full sync rescan across all registered iCloud containers:

Bash

brctl monitor com.apple.CloudDocs

  1. Press Control + C to exit the monitoring stream once file events start populating.

Post-Fix Verification: Open Finder, create a new test text document on your Desktop, and check if it syncs to iCloud.com within 30 seconds.

Long-Term Maintenance & Prevention Practices

To keep iCloud Drive sync operations stable and prevent daemon locks across future macOS updates:

1. Maintain At Least 15% Free Local Storage

macOS requires adequate local disk space to stage temporary files during two-way sync operations. If your internal SSD falls below 10–15 GB of free space, bird will automatically restrict sync jobs to prevent complete storage exhaustion.

2. Avoid Special Characters in File and Folder Names

While macOS supports most Unicode characters, file names containing leading spaces, trailing spaces, or reserved characters (such as :, /, or \) can cause sync failures when communicating with CloudKit servers. Keep file names alphanumeric and use underscores or hyphens instead of special characters.

3. Exclude Active Developer & Database Directories

Never place active Git repositories, node_modules folders, or live database storage files (such as MySQL or Xcode build build caches) inside your Desktop or Documents folders if iCloud sync is enabled. The thousands of rapid small-file writes generated by these tools overload bird and trigger sync throttling. Use .nosync as an extension (e.g., my_project.nosync/) to force iCloud to ignore specific folders.

Leave a Comment