iCloud and cloud storage

When two Macs disagree

Updated 2026-07-31 · 4 min read

Sync failures are usually one machine's problem. The first job is working out whose.

Find the guilty machine

Edit a small text file on Mac A; check iCloud.com (not the other Mac) for the change.

• Change visible on the website → A uploads fine; the problem is B's downloads
• Not visible → A is not uploading

iCloud.com is the arbiter, because it shows the server's truth without a second Mac's sync state confusing the picture.

On the guilty machine

1. Disk space — full disks stall sync silently
2. System Settings → Apple ID → iCloud → iCloud Drive — confirm it is on, and that the

specific app's toggle is on for app-container syncing

1. Pause and resume: toggling iCloud Drive off and on forces a metadata re-evaluation

(choose "keep a copy" when asked; nothing is lost)

1. killall bird — the standard pipeline kick

Reading the log

brctl log --wait --shorten

Repeated errors about one path identify a poison file — often something with an unusual name, an enormous size, or a package an app is holding open. Move it out of iCloud Drive, let sync settle, then reintroduce it.

Names that break sync

Files ending in a space or dot, extremely long paths, and certain characters upset the pipeline quietly. If the log names such a file, rename it locally and sync resumes.

What not to do

Do not delete ~/Library/Mobile Documents (the real iCloud Drive folder) hoping to force a fresh sync — that deletes your files, and the deletion syncs. The sign-out/sign-in sequence is the sanctioned reset.

Common questions

How do I tell which Mac is failing to sync?

Check iCloud.com after editing a file. The website shows the server's state, isolating upload from download problems.

Can a single file block iCloud sync?

Yes — a problem file can stall the queue. brctl's log names it; moving it out restores flow.