ID: 20260822051700

Yes. On modern macOS, iCloud Drive is no longer one single “iCloud process.” It is a stack involving CloudKit, File Provider, Finder integration, metadata/indexing, and background transfer services.

A useful overview—especially when troubleshooting files that are stuck downloading/uploading—is:

The most important relationship

For an iCloud Drive file, I’d visualize the modern architecture roughly like this:

                         APPLE / iCLOUD
                              │
                              │ CloudKit / network
                              ▼
                         ┌──────────┐
                         │  cloudd  │
                         └──────────┘
                              │
                     cloud coordination
                              │
             ┌────────────────┴───────────────┐
             │                                │
          ┌──────┐                    ┌───────────────┐
          │ bird │                    │ fileproviderd │
          └──────┘                    └───────────────┘
             │                                │
             │                         File Provider
             │                         domains/items
             │                                │
             └──────────────┬─────────────────┘
                            │
                            ▼
              ~/Library/Mobile Documents/
                    com~apple~CloudDocs/
                            │
                 ┌──────────┴─────────┐
                 ▼                    ▼
              Finder              applications
                 │
                 ▼
          user opens/copies/
          downloads/evicts file

One complication is that Apple is in a transition from the older Documents-in-the-Cloud/Bird architecture toward File Provider infrastructure, so you can encounter both old and new terminology and components. That is one reason logs can be confusing.

For the troubleshooting you’ve been doing

I’d divide the processes into four layers:

For your purposes, I would pay by far the most attention to these three:

cloudd
fileproviderd
bird

They answer somewhat different questions:

cloudd — “Can macOS talk to Apple’s cloud database/services?”

You have already seen entries such as:

cloudd[...] [com.apple.cloudkit:Request]

Those are CloudKit operations. A request ending with:

Finishing with error (null)

normally means that particular CloudKit request completed without an error.

fileproviderd — “What should this file look like locally, and should it be downloaded?”

This is especially interesting when investigating things such as:

cloud file exists
       │
       ▼
placeholder exists locally
       │
       ▼
download requested
       │
       ▼
materialization
       │
       ▼
actual bytes exist locally

And importantly, fileproviderd isn’t just iCloud. It is also involved with providers such as Dropbox. That’s why your logs contain things like:

[com.apple.FileProvider:com.getdropbox.dropbox.fileprovider/...]

So when reading fileproviderd logs, the File Provider domain/provider identifier matters enormously. An error from fileproviderd is not automatically an iCloud error.

bird — “Is the iCloud Drive synchronization state consistent?”

bird is worth watching when the problem appears specifically limited to iCloud Drive rather than File Provider generally.

A practical live troubleshooting command is therefore:

log stream --style compact \
  --predicate 'process == "bird" OR process == "cloudd" OR process == "fileproviderd"'

For a broader picture:

log stream --style compact \
  --predicate 'process == "bird" OR
               process == "cloudd" OR
               process == "fileproviderd" OR
               process == "nsurlsessiond" OR
               process == "accountsd" OR
               process == "appleaccountd"'

And when troubleshooting iCloud versus Dropbox, I would actually treat fileproviderd as the common middle layer:

                    macOS
                      │
               fileproviderd
                /           \
               /             \
        iCloud domain      Dropbox domain
             │                  │
          iCloud              Dropbox
        infrastructure      infrastructure

That distinction is particularly useful because a fileproviderd problem affecting multiple providers points toward macOS/File Provider itself, while a problem seen only in the Dropbox domain points much more strongly toward Dropbox’s File Provider implementation.

If you’d like, I can next make a much more detailed “macOS Cloud Process Map”, including bird, cloudd, fileproviderd, nsurlsessiond, accountsd, apsd, Spotlight, Finder, and the relevant command-line tools, with a column for “safe to kill/restart?” and exactly what happens when you do.

ID: 20260826112200

For cloudd troubleshooting, I would work from observation → isolate CloudKit errors → restart → investigate account/cache only if necessary. cloudd is used by more than iCloud Drive, so simply seeing lots of cloudd activity does not mean iCloud Drive itself is malfunctioning.

1. Establish whether cloudd is actually unhealthy

Check that it is running:

pgrep -lf cloudd

and resource consumption:

ps -axo pid,%cpu,%mem,etime,command | grep '[c]loudd'

For a better live view:

top -pid "$(pgrep -x cloudd)"

Things I’d consider suspicious are sustained high CPU, rapidly increasing memory, repeated crashes/restarts, or the same CloudKit request/error repeating continuously.

2. Watch cloudd alone

This is my preferred starting point:

log stream --style compact \
    --info \
    --predicate 'process == "cloudd"'

For historical activity, for example the last hour:

log show --last 1h \
    --style compact \
    --info \
    --predicate 'process == "cloudd"'

Because the output can be enormous, look first for errors:

log show --last 1h \
    --style compact \
    --predicate 'process == "cloudd" AND messageType == error'

But be careful: Apple’s unified logging uses “error” fairly liberally. An error-level log entry is not necessarily evidence that the operation failed.

3. Search for genuinely interesting patterns

I’d use:

log show --last 1h --style compact \
    --predicate 'process == "cloudd"' |
egrep -i 'error|failed|failure|timeout|timed out|network|account|auth|token|retry|throttl|quota'

A particularly important distinction is between an intermediate scary-looking message and the final result of the CloudKit request.

For example, the entry you showed previously:

[com.apple.cloudkit:Request]
req: 4E4AE6DA-...
"Finishing with error (null)"

is actually reassuring:

error (null)
      ↑
      no error object

So I would not treat that line itself as evidence of failure.

4. Follow one CloudKit request from beginning to end

This is much more useful than grepping random cloudd errors.

If you see:

req: 4E4AE6DA-1E8E-42D8-B545-9242FD801CBB

take that UUID and run:

log show --last 1h --style compact \
    --predicate 'process == "cloudd"' |
grep '4E4AE6DA-1E8E-42D8-B545-9242FD801CBB'

You can then reconstruct:

request created
      ↓
request scheduled
      ↓
network transaction
      ↓
CloudKit response
      ↓
retry / processing
      ↓
Finishing with error (...)

That gives us considerably better evidence than individual log lines.

5. Correlate cloudd with the other cloud processes

For an iCloud Drive problem, I’d normally run:

log stream --style compact --info \
    --predicate 'process == "cloudd" OR
                 process == "bird" OR
                 process == "fileproviderd"'

Then deliberately trigger the problem—for example:

icloud status "/path/to/problem-file"

or request that the file download in Finder.

We can then see whether the chain looks like:

Finder / user action
        ↓
fileproviderd
        ↓
bird / iCloud coordination
        ↓
cloudd
        ↓
CloudKit
        ↓
Apple

This is important because cloudd may be functioning perfectly while fileproviderd is where the operation gets stuck.

6. Safely restart cloudd

A relatively low-impact test is:

killall cloudd

macOS should automatically relaunch it through launchd.

Then:

pgrep -lf cloudd

You should see a new PID.

I’d do this while watching:

log stream --style compact \
    --predicate 'process == "cloudd"'

This gives you a useful test:

Problem disappears after restarting cloudd → stronger evidence of stale daemon/session/cache state.

Problem remains unchanged → start looking harder at bird, fileproviderd, account state, networking, or the particular CloudKit container.

7. Check whether it is continuously restarting

Run:

while true; do
    date
    pgrep -lf cloudd
    sleep 5
done

The PID should normally remain stable. If you see:

1234 cloudd
1234 cloudd
1234 cloudd
1789 cloudd
1789 cloudd
2142 cloudd

without you killing it, that’s significant. We’d then want to investigate crashes/termination rather than synchronization.

You can check recent logs for termination:

log show --last 1h --style compact \
    --predicate 'process == "cloudd"' |
egrep -i 'crash|abort|terminate|exit|fault'

8. Don’t delete cloudd databases/caches yet

There are various Internet recipes involving deleting things under ~/Library/Caches, ~/Library/Application Support/CloudDocs, CloudKit databases, signing out of iCloud, etc.

I would not do any of those yet.

Given the kind of File Provider/iCloud investigation we’re doing, destroying state too early removes evidence and can trigger a huge resynchronization. We should first establish whether cloudd is actually the failing component.

A diagnostic capture I’d like to see

The most useful next experiment would be to pick one iCloud file that refuses to download, then start:

log stream --style compact --info \
  --predicate 'process == "cloudd" OR
               process == "bird" OR
               process == "fileproviderd"'

Then request Download Now for that single file, wait perhaps 30–60 seconds, and stop logging with Ctrl-C.

Paste that section here. I can separate the noise into the three layers and identify which daemon receives the request, where it progresses, and where the chain stops.