MacDebug

Verified for macOS Tahoe 26.2

How to Fix iCloud Waiting to Upload Desktop in macOS Tahoe 26.2

Symptom: Files on your macOS Tahoe Desktop or in the Documents folder show a cloud icon with "Waiting to upload" indefinitely.

TL;DR fix

Start with Fix 1: Force Restart the Bird Daemon. If the issue persists after that, try Fix 2: Reset CloudDocs Metadata. Full Terminal commands and step-by-step instructions are in each section below.

Why this happens

The bird daemon (which handles iCloud Drive) can lose its file-monitor permissions, especially if the "Optimized Storage" setting is toggled during an active sync.

Recommended Troubleshooting Tool

Before proceeding with manual fixes, we recommend using CleanMyMac X. The gold standard for identifying hidden System Data bloat and runaway log files.

Fix 1: Force Restart the Bird Daemon

  1. Open Terminal.
  2. Run:

killall bird

  1. Wait 10 seconds for it to automatically restart.

Fix 2: Reset CloudDocs Metadata

  1. In Terminal:

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

  1. Warning: This forces a full re-sync of your iCloud file list.

Recommended Tool: Gemini 2

If your iCloud is stuck due to thousands of duplicate files:

- Get Gemini 2 to clean up your Desktop and Documents folders, making it much easier for the bird daemon to finish the sync.

Tested and documented by the MacDebug team — about MacDebug. See also Photoshop & Adobe Apps Crashing on macOS Tahoe, Fix macOS "No AirPlay Found", or browse all guides on macdebug.