iCloud Drive stuck syncing on Mac: practical fixes for developers

iCloud Drive stuck syncing on Mac usually looks harmless at first. One file says waiting. Finder shows a tiny cloud icon. Then bird or cloudd starts eating CPU, the upload count does not move, and every project folder feels slower than it should.

For normal documents, the usual advice can work: restart the Mac, check storage, sign out of iCloud, wait. Developers have a different problem. A single workspace can contain 40,000 tiny files before lunch. iCloud Drive was not designed to treat node_modules, .next/cache, build output, coverage reports, and Git worktrees as quiet office documents.

This guide is for that version of the problem: iCloud sync stuck because your Mac is trying to watch too much disposable project noise.

Why iCloud Drive gets stuck syncing on Mac

iCloud Drive sync has to notice local changes, compare metadata, upload files, resolve conflicts, and keep Finder state current. That is fine for a few PDFs. It gets ugly when thousands of files appear and disappear in seconds.

A few developer habits make the stuck syncing problem worse:

The file size is often not the issue. A 900 MB video can be simpler than 35,000 tiny dependency files because iCloud has to track each file separately.

Quick checks before you reset iCloud Drive

Do not start by signing out of iCloud. That can create a bigger cleanup job. Check the boring causes first.

Check whether one project folder is the source

Open Activity Monitor and search for bird and cloudd. If one of them is busy, look at what changed recently. Did you install dependencies? Did a build tool write a cache? Did a test run produce coverage files?

You can also check rough file counts from Terminal:

```bash

find ~/Library/Mobile\ Documents/com~apple~CloudDocs -type f | wc -l

find ~/Library/Mobile\ Documents/com~apple~CloudDocs -name node_modules -type d -prune -print

```

If the second command prints project folders, that is a strong clue. You probably do not want iCloud touching those directories at all.

Look for sync icons that never clear

Finder can show whether a folder is waiting, uploading, or downloaded locally. Drill into the folder with the stuck icon. If the problem sits inside node_modules, .next, build, or another generated directory, fixing the folder is better than resetting the whole account.

Check storage on both sides

A full local disk or full iCloud plan can leave sync half-finished. Keep several gigabytes free locally and check iCloud storage before changing settings. This is less exciting than debugging daemons, but it catches plenty of cases.

Fixes that usually work

Start with the least destructive option. The goal is to stop feeding iCloud files it should never have watched.

Move generated folders out of iCloud

Delete generated folders from the synced project, then recreate them outside iCloud or let your package manager rebuild them after you move the project. For Node projects, that means removing node_modules from the iCloud-backed location and running install again after you decide where the project should live.

Keep source code in sync, not dependencies

Your code, docs, and small config files are worth syncing. Dependencies, caches, and build artifacts are replaceable. Treat them that way.

If you want projects to remain under iCloud Drive, use rules to exclude the noisy parts. Lsyncer was built for exactly this Mac developer problem: keep useful folders synced while skipping node_modules, .next, dist, build, logs, and caches.

Restart sync only after removing the noisy folder

Once the bad folder is gone, a restart can help iCloud catch up. Rebooting before removing the file flood often just makes the same queue start again.

If Finder still shows stale icons, leave the Mac awake on power for a while. iCloud Drive is not fast, and forcing repeated resets can make the state harder to read.

When to avoid the nuclear options

Signing out of iCloud, deleting the local iCloud Drive cache, or wiping CloudDocs can work, but they are last-resort moves. They can trigger full re-downloads, duplicate files, or conflict copies. If the root cause is a project folder generating thousands of files, the problem will come back after the reset.

Use the bigger reset only when ordinary documents are stuck too, storage is fine, and you have a backup. For developer folders, fix the file pattern first.

A better setup for Mac development folders

A calmer setup is simple:

This is not about making iCloud perfect. It is about giving it work it can actually finish.

FAQ

Why is iCloud Drive stuck syncing on my Mac?

Common causes include low storage, network trouble, a stuck Apple process, or too many changing files. For developers, generated folders such as node_modules, build output, and caches are often the real trigger.

Is it safe to delete node_modules from iCloud Drive?

Yes, if it belongs to a development project and you can reinstall dependencies from package.json and your lockfile. Do not delete folders you cannot recreate. Commit your source code to Git first if you are unsure.

How do I stop iCloud from syncing a folder on Mac?

macOS does not offer a simple per-folder exclude list for iCloud Drive. You can move the folder outside iCloud, use project structure changes, or use a focused tool such as Lsyncer to keep generated folders out of sync.

Should I sign out of iCloud to fix stuck syncing?

Only after safer checks. Signing out can force a large re-sync and create conflict files. If one development folder caused the queue, remove or exclude that folder first.

Why does iCloud Drive struggle with developer projects?

Developer projects create many small files quickly. Sync systems have to track each file, not just the total folder size. That makes dependency folders and caches much harder than normal documents.

Keep iCloud useful without letting it babysit junk

Syntanea builds small practical tools when we hit a real workflow problem ourselves. Lsyncer came from exactly that: Macs slowed down by iCloud trying to sync files that should never leave the machine.

If your iCloud Drive is stuck because a development folder got noisy, clean up the generated files first. Then set rules so it does not happen again. That beats resetting sync every few weeks.