iCloud Drive Not Syncing: Checks Before You Move Machines
A file saved on the desk Mac an hour ago is still not on the laptop. The Finder shows a cloud icon with an arrow in it, or a dotted circle that has been half full since lunch, or nothing at all where a folder should be. The timing is rarely convenient, because the searches for this happen the evening before a trip or the morning a replacement machine arrives.
The useful move is to stop reloading the Finder window and work through the causes in the order that actually finds them. Most cases come down to one of four things: the two machines are not on the same Apple Account, sync is switched off for that Mac, iCloud storage is full, or the file is there and simply has not been downloaded yet.
Start with the four checks that find most cases
Open System Settings, click the name at the top, then iCloud, then Drive. There are two separate controls in that panel and both have to be right.
Sync this Mac is the one that decides whether this machine participates at all. Apple's own instructions for the Desktop and Documents feature make it a prerequisite step:
Click Drive (or iCloud Drive). Below iCloud Drive, check that you turned on Sync this Mac. Source: support.apple.com
It gets switched off by accident more often than seems plausible, usually while someone is trying to free up disk space.
Second, compare the Apple Account email on both machines, character by character. Two accounts with similar addresses, one personal and one set up years ago for a work device, produce exactly the symptom being investigated: both Macs look signed in, both show iCloud Drive in the sidebar, and the two sidebars are showing different storage.
Third, check the storage figure in that same panel. A full account stops uploading and reports nothing in the Finder except files that never finish.
Fourth, rule out the service rather than the machine. Apple publishes a live status list at the system status page, and iCloud Drive has its own row there. If that row is not green, nothing done locally will help, and the correct action is to wait rather than to start turning features off and on.
What the Finder is telling you
The icons next to a file name are a status report, and reading them saves a great deal of guessing.
A cloud outline with a downward arrow means the file exists in iCloud and is not on this Mac's disk yet. Nothing is broken. Clicking it downloads it. This is the single most common false alarm, and it is produced deliberately by the setting that keeps only recently used files on the local disk.
A dotted or partially filled circle means a transfer is in progress. If it sits still for a long time on a small file while other transfers complete, the account is usually out of storage.
A file labelled Ineligible is refusing to upload by design. Apple lists which library formats are excluded from the Desktop and Documents folders:
iCloud Drive won't upload these types of library files from your Desktop folder and Documents folder to your other devices: iMovie libraries, Photos libraries, Aperture libraries. They're labeled as Ineligible in the Finder. Source: support.apple.com
That is worth knowing before a migration, because a Photos library sitting on the Desktop of the old Mac is not going to appear on the new one, no matter how long sync is left running.
To free up local space on purpose rather than by accident, the documented control is to hold the file and choose Remove Download, which removes the local copy and leaves the file in iCloud. It looks identical to a file that failed to sync, which is why the icon reading comes first.
Desktop and Documents is where the confusion starts
Turning on Desktop and Documents Folders moves both folders into iCloud Drive, and the result surprises people in two ways.
The first is the location. In macOS Tahoe 26 and later the Desktop and Documents folders appear in the Finder sidebar under Favorites with a cloud icon next to the name. In earlier versions they sit in the iCloud section of the sidebar instead. Anyone looking in the home folder for files that are now held in iCloud Drive finds an empty pair of folders and concludes sync has eaten them.
The second is what happens with two Macs. Both machines have a Desktop, and iCloud Drive does not merge them. The second Mac's Desktop shows up as a separate folder inside the Desktop folder in iCloud Drive, named after that Mac. So the file is present and it is one level deeper than expected. Spotlight finds it in a second, and a recursive look through the Desktop folder finds it too.
Deletion works the way it does in every synced folder, which is to say it applies everywhere. A file deleted on one device is deleted on every device signed into the same Apple Account, and it goes to Recently Deleted, where it stays for 30 days before removal. That 30 day window is the safety net for a migration that went wrong, and it is finite.
One more Finder habit is worth adopting during a migration. Sorting a folder by size with the view options showing all items, rather than trusting the summary at the bottom of the window, reveals the handful of large items that are holding up everything behind them. Transfers are not strictly ordered, but a single multi gigabyte file on a slow connection will make every small document that follows it look stalled, and that misreading is what sends people into the settings to switch features off.
Storage is the quiet cause
A full account produces no error dialog worth the name. It produces transfers that never complete, which reads locally as a sync fault. The free allowance and the paid tiers are published:
iCloud keeps your information safe, automatically backed up, and available anywhere you go, with 5 GB of storage for free. Source: support.apple.com
| Tier | Storage | Notable additions |
|---|---|---|
| Free | 5 GB | Included with the Apple Account |
| iCloud+ | 50 GB | Private Relay, Hide My Email, Custom Email Domain, one HomeKit Secure Video camera |
| iCloud+ | 200 GB | Same features, up to five HomeKit Secure Video cameras |
| iCloud+ | 2 TB, 6 TB or 12 TB | Same features, unlimited HomeKit Secure Video cameras |
Every iCloud+ tier can be shared with up to five other family members, which matters for a household where one person is out of space and another has room to spare. Monthly prices differ by country and region, so the figure to act on is the one shown in the purchase panel on the machine, not a number quoted elsewhere.
Turning Desktop and Documents Folders on is the fastest way to overrun a 5 GB allowance, because a working Desktop is frequently larger than the whole free tier on its own.
What iCloud Drive does not carry
iCloud Drive is a file service, and the reason a migration still feels unfinished after every file has arrived is that the working parts of the day are not files.
| Item | Travels in iCloud Drive |
|---|---|
| Documents, images, archives | Yes |
| Desktop and Documents folders | Yes, when that setting is on |
| iMovie, Photos and Aperture libraries in those folders | No, labelled Ineligible |
| Browser sessions and site logins | No |
| Browser profiles and extension data | No |
| Which web apps were open and where | No |
| Application preferences outside iCloud | No |
| Files inside another cloud service's folder | No, and this causes conflicts |
The last row is worth stating plainly. Apple's guidance is to keep third party cloud folders somewhere other than the synced Desktop and Documents folders, and to turn off any feature from another provider that manages those same two folders. Two services managing one folder produces duplicate files with machine names appended, and it looks exactly like an iCloud fault.
The order to work through before moving machines
For a migration rather than a repair, sequence matters, because several of these steps cannot be done once the old Mac has been wiped.
Confirm both Macs show the same Apple Account, then confirm Sync this Mac is on for both. Check the storage figure and buy a tier if the total will not fit, since the upload has to complete before the new machine can download anything. Then force the upload to finish while the old Mac is still available: leave it awake, plugged in, and on a network, because sleep pauses the transfer and a laptop lid closed overnight is the most common reason an upload was still running in the morning.
Next, deal with the exclusions by hand. Move any Photos or iMovie library off the Desktop and copy it directly, because iCloud Drive will not take it. Check for Ineligible labels and resolve each one.
Finally, if iCloud Drive is being turned off on the old machine, know what that does. The files stay in iCloud Drive and new empty Desktop and Documents folders are created locally, and there is an option to keep a local copy:
If you keep a local copy of your files, they copy to a folder called iCloud Drive (Archive) in your home folder. Source: support.apple.com
That archive folder is the thing to look for when files seem to have vanished after somebody signed out of iCloud in a hurry.
The files arrive, the working setup does not
Once every file has landed, the new Mac is still a day's work away from being the old one, and the gap is the browser. Site sessions, which web apps were open, which account each window belonged to, and the notification settings that stopped three chat tools shouting at once are all outside the reach of a file sync service. Rebuilding that by hand is the part nobody budgets for.
Narrowing that gap means putting the setup somewhere more durable than a browser profile folder. A browser that keeps each web application in its own window holds Gmail, Slack, a client dashboard and an admin console as separate windows with separate sessions, so the arrangement is a defined set of applications rather than a pile of tabs that has to be reconstructed from memory. The Workspaces page sets out how those sessions stay separate, and Supported apps lists the services already configured. For anyone weighing the options in the category, Compared with Rambox puts them side by side.
What to change first
Read the Finder icon before changing any setting, because a cloud with an arrow means the file is fine and simply not downloaded. Then check that both Macs are on the same Apple Account with Sync this Mac on, and check the storage figure, since a full account looks exactly like a broken one. Once the files are settled, the part still missing is the browser setup, and that is what a SpaceDeck style window per application arrangement makes reproducible instead of hand built.
Frequently asked questions
How long should iCloud Drive take to sync?
Small documents normally appear within a minute of the other device being online. A large upload takes as long as the connection allows, and it pauses when the Mac sleeps, so a laptop with the lid closed makes no progress at all. A transfer stuck on a small file while others complete points at full storage rather than at speed.
Why do the files show a cloud icon instead of opening?
Because the file lives in iCloud and the local copy has been removed to save disk space. Clicking it downloads it again. This is normal behaviour rather than a fault, and it is the setting that keeps only recently used files on the disk doing its job.
Where did the Desktop files go after turning on Desktop and Documents Folders?
They are in iCloud Drive, not in the home folder. In macOS Tahoe 26 and later the two folders appear in the Finder sidebar under Favorites with a cloud icon, and in earlier versions they appear in the iCloud section of the sidebar. A second Mac's Desktop appears as a folder named after that Mac inside the Desktop folder.
Can Dropbox or Google Drive run alongside iCloud Drive?
Yes, provided they manage different folders. Apple's guidance is to keep another provider's folders somewhere else, such as the home folder, and to turn off any feature from that provider which syncs or manages the Desktop and Documents folders. Two services managing one folder produces conflicted duplicates.
Does iCloud Drive move browser logins to a new Mac?
No. It moves files. Browser sessions, cookies, profile data and extension storage are not files it carries, so a new Mac with every document in place still starts signed out of every web app. Saved passwords in the keychain help, but each site is signed into once more.