Mac iCloud Sync Errors — Documents Not Syncing & Upload Failures

Overview

Fix iCloud Drive sync issues including documents stuck uploading, version conflicts, storage full errors, and Desktop & Documents folder sync failures.

Key Details

• iCloud Drive syncs files via the bird and cloudd daemon processes
• Files show cloud icons in Finder: download arrow (not local), checkmark (synced), progress (syncing)
• Desktop & Documents sync moves those folders to iCloud, which can be confusing
• iCloud storage full prevents new uploads but existing synced files remain accessible
• Conflicted copies appear as 'filename (conflict)' when two devices edit simultaneously

Common Causes

• iCloud storage full preventing new file uploads
• Poor internet connection causing sync timeouts
• bird or cloudd process crashed and not restarting
• File locked by an application preventing iCloud from syncing changes
• Apple ID authentication issue requiring re-sign-in

Steps

1. 1Check iCloud status: System Settings > Apple ID > iCloud > verify storage and sync status
2. 2Restart iCloud sync: killall bird in Terminal (it auto-restarts)
3. 3Check for stuck files: look for .icloud placeholder files that have not downloaded
4. 4Force download a file: brctl download /path/to/file.icloud
5. 5Sign out of iCloud and sign back in: System Settings > Apple ID > Sign Out (keep a copy of data)

Tags

Frequently Asked Questions