iCloud Status Icons in Finder Explained

Finder annotates iCloud Drive files with a small vocabulary of badges — clouds, arrows, progress circles — and it never explains any of them. Each one answers the only question that matters: is this file actually on my Mac right now? Here's the full decoder, plus what to do when an icon signals trouble.

The icons, decoded

• No badge at all — the good state. The file is fully downloaded, lives on your disk, and is synced with iCloud. It opens instantly, works offline, and gets captured by Time Machine.
• Cloud with a downward arrow — online-only. The file exists in iCloud but not on this Mac; what you see is a placeholder. Double-click and macOS downloads it before opening. Files get this way when you (or a family member sharing the folder) chose Remove Download, or when Optimize Mac Storage evicted them automatically to free disk space.
• Circular progress pie — a transfer is in flight, filling as it goes. Next to a file you just added it means uploading; next to a placeholder you just opened it means downloading. Folders show one for their contents in aggregate.
• Cloud with an upward arrow — waiting to upload. The file is safe locally but hasn't reached iCloud yet, so it won't appear on your other devices. Normal for a few minutes after saving; a problem if it persists for hours.
• Cloud with a slash (struck-through cloud) — this item can't sync. Either the file is ineligible or iCloud Drive is off for it. Some system-managed items simply don't sync; for your own files, a struck cloud usually means sync is paused or broken account-wide.
• Cloud with an exclamation mark — an error state: iCloud hit a problem with this specific item, commonly a full iCloud quota or a conflicted file.
• Folder with a person silhouette — a shared folder. Not a health state at all: it just marks folders other people can access, whether you shared them or accepted someone's invitation.

Folders aggregate their contents' states, so a single online-only file three levels deep is enough to badge the folder above it — drill down before assuming a whole folder is missing.

For a less cryptic view, switch to list view (⌘2) inside iCloud Drive — on macOS Sonoma and later you can right-click the column headers and enable an iCloud Status column that spells states out in words ("Downloaded", "Waiting to Upload") instead of badges.

What to do about the trouble states

1. Stuck "waiting to upload": confirm you're online and your iCloud quota isn't full (System Settings → your name → iCloud — a full bar silently stops all uploads). Then give the sync daemon a kick from Terminal; it relaunches itself automatically:

# restart the iCloud Drive sync daemon (respawns on its own)
killall bird

2. Exclamation cloud: check quota first. If storage is fine, open the file — macOS often surfaces a conflict dialog (two devices edited the same file) letting you keep one or both versions.
3. Everything suddenly online-only: that's Optimize Mac Storage doing its job on a full disk. If you'd rather keep full local copies, turn it off at the bottom of System Settings → your name → iCloud — and undo later by flipping it back on if disk space becomes a problem again.

One habit worth forming

Before a flight or a spotty-Wi-Fi week, scan the folders you'll need for downward-arrow clouds, select the lot, right-click, and hit Download Now. The icons exist precisely so you can spot "not actually here" at a glance — thirty seconds of scanning beats discovering a placeholder at 30,000 feet.