“The operation can’t be completed because the item needs to be downloaded”

You dragged a folder out of iCloud Drive — onto an external disk, into a backup, over to a USB stick — and Finder stopped with “The operation can’t be completed because the item needs to be downloaded.”

The files are right there in the list. They have names, they have sizes, some of them have thumbnails. What they do not have is any content on your Mac.

For a single such file, FileBo is the quick route: open it from FileBo’s recents panel and the content comes down like it would in any reader. For a whole folder it is not the tool — the recipes below are.

The rest of this page is the machinery: what Finder is really telling you, what a placeholder is on current macOS, how to see which of your files are hollow, how to force one file or a whole folder down, and what to do when the download itself is the thing refusing.

Finder’s exact wording, and the six messages filed next to it

The wording is not improvised. macOS keeps a fixed list of the ways a cloud file can fail to arrive, and this message is one line on that list. The lines filed either side of it are the useful part: they are the reasons a download does not happen, and one of them is your reason.

Want to read them on your own Mac? macOS 26.6 keeps this message in Finder’s own string table, at /System/Library/CoreServices/Finder.app/Contents/Resources/en.lproj/LocalizableMerged.strings. There are two variants:

CS201 = "The operation can’t be completed because “^0” needs to be downloaded."
CS202 = "The operation can’t be completed because the item needs to be downloaded."

^0 is Finder’s placeholder for a file name — you get CS201 when the dialog knows which file stopped it, CS202 when it does not. The apostrophe in can’t is a typographic one, U+2019, which is part of why searching for this error with a straight quote finds fewer pages than it should.

Six more messages sit immediately after those two, and together they are one family: every way a cloud provider can decline to hand a file over.

Finder’s message	What it is telling you
“name” needs to be downloaded	the bytes are not on your Mac
the item needs to be downloaded	the same, without a name to show
Authentication needed to complete this operation.	signed out of the provider
Could not connect to the server.	provider unreachable
Insufficient space to complete this operation (quota limit reached).	cloud quota, not disk space
Extension internal error.	the provider’s own extension failed
Authentication needed for “name” to complete this operation.	per-provider sign-in
Could not connect to “name”.	per-provider connection

That table is the whole point of this page. This is not an error about copying. It is an error about downloading. Everything below follows from it.

What a placeholder actually is on current macOS

A placeholder is a file with everything except the file. The name is real, the size is real, the icon is real; the contents are still up in the cloud. On current macOS there is no second, hidden stand-in sitting next to the real one — it is the same file, hollowed out, which is why nothing looks wrong until something tries to read it.

Most guides on this subject describe a hidden file called .YourReport.pdf.icloud sitting where the real one should be. That is the older shape, and on my Mac it is not what you get.

I put a 53-byte file in iCloud Drive, waited for it to upload, evicted it with brctl evict, and looked at what was left:

$ ls -lO testfile.txt
-rw-r--r--@ 1 me  staff  compressed,dataless 53 Aug  8 12:46 testfile.txt

$ stat -f 'size=%z blocks=%b flags=%Sf' testfile.txt
size=53 blocks=0 flags=compressed,dataless

Real name, real size, zero blocks. The marker is a file-system flag called dataless, not a sidecar file — a search for *.icloud across the whole of ~/Library/Mobile Documents returned nothing at all, before the eviction or after it.

That one word is the most useful thing on this page, because it answers “which of these files are actually here?” in a single line.

Check your own Mac:

find ~/Documents -type f -flags +dataless

On a test folder of six files with five of them evicted, it printed exactly those five and left out the one that was downloaded. No sudo, no third-party tool.

Two things a placeholder keeps doing, which is why it catches you out. It still reports a size — ls -l said 53 bytes and du said 0B, both correct, measuring different things. And it is still indexed: mdfind found my evicted file while it was still dataless. A file can therefore appear in a search and then refuse to copy, which is one flavour of the split described in Spotlight finds it, Finder doesn’t.

The legacy .icloud stub has not vanished from the world, and you will still meet it on older systems. Where you see one, the real name is the stub’s name with the leading dot and the .icloud suffix removed.

Where the placeholders came from

Nothing was deleted and nobody made a mistake. One setting decided that your disk was getting tight and that these particular files could live in the cloud instead of on the Mac.

In System Settings it lives under your Apple Account, inside iCloud ▸ iCloud Drive, in the Saved to iCloud group — Apple shuffles that hierarchy between releases, so go by the wording rather than by the clicks. The toggle is Optimize Mac Storage, and macOS renders it Optimise Mac Storage in British and Australian English — same switch, and worth knowing if you are searching for it. Its own description, as macOS words it on 26.6:

The full contents of iCloud Drive will be stored on this Mac if you have enough space. Older documents will be stored only in iCloud when space is needed.

Read that sentence for its timing rather than its promise. Nothing is evicted while you have room. Files start turning into placeholders when the disk fills, chosen by age, without asking — which is why the failure shows up months after you enabled the setting, and never on the Mac you happened to be testing on.

Forcing one file down

For a single file the fix is boringly simple: something has to read it. Open it, copy it, move it out of the cloud folder — anything that actually touches the contents makes macOS go and fetch them, and afterwards it is an ordinary file again. There is nothing to repair and no setting to change.

In Finder: right-click and choose Download Now. In Finder’s string table that command sits in the same block as Move to Trash and Put Back, alongside Remove Download, Keep Downloaded, Do Not Sync / Sync and Show Downloaded Folder — the whole cloud contextual menu lives there, which is a decent list of the words to look for when a provider’s own menu is worded differently.

In Terminal, the thing worth knowing is that there is no special command. Reading a dataless file downloads it.

Try it on one file:

cat "yourfile.pdf" > /dev/null

I ran that on an evicted file and the flag went from compressed,dataless to nothing, with the content printed correctly. cp does the same in passing: copying a placeholder produced a complete file on the far side and left the source materialised.

mv is the one to be careful with, and it is the trap in this whole section. Moving a placeholder out of iCloud Drive — to ~/Documents, to /tmp, to an external disk — downloads it, because the move has to read the bytes to write them elsewhere. Moving it within iCloud Drive does not:

$ cd ~/Library/Mobile\ Documents/com~apple~CloudDocs
$ mv report.pdf Archive/report.pdf
$ ls -lO Archive/report.pdf
-rw-r--r--@ 1 me  staff  compressed,dataless 247370 ... report.pdf

That is a rename inside one provider, nothing is read, and the file is exactly as absent as it was. Tidying your iCloud Drive into folders does not bring anything down, however long it takes.

You will find brctl download recommended everywhere, and on a single file it works, with two caveats I measured. It is undocumented — brctl’s own usage output on macOS 26.6 lists diagnose, log, dump, status, accounts, quota and monitor, and no download — though the tool certainly knows the word, because anything it genuinely does not know comes back as brctl: No such operation. And it is asynchronous: it returned exit code 0 immediately with the file still dataless, and the content landed a few seconds afterwards, on iCloud’s schedule rather than the command’s. Don’t read the timing as a constant — the useful part is that the exit code says nothing about whether the bytes arrived. If you script around it, you are not waiting for what you think you are waiting for.

Forcing a whole folder down

This is the case that actually brings people here — a backup, a disk migration, moving a project off the machine.

There is no “download everything” button hiding in macOS, and the command everybody recommends for the job quietly does nothing on a folder. What works is making something read every file in turn, which sounds like a chore and is one line.

Start with what does not work. I evicted six files, ran brctl download on the enclosing folder, got exit code 0, and forty seconds later all six were still flagged dataless. On a directory it reports success and does nothing.

Terminal is the route I can vouch for — one line, which is only the read trick applied recursively:

find ~/Documents/Archive -type f -exec cat {} + > /dev/null

Every file gets read, and every read materialises. Size the job before you start it, because you are about to pull an entire folder out of the cloud onto a disk that was short of space to begin with — and du is the wrong ruler here: an evicted file occupies zero blocks, so du reports the folder as nearly empty right up until the download lands. Count and weigh the evicted files by their logical size instead:

find ~/Documents/Archive -type f -flags +dataless -exec stat -f '%z' {} + |
  awk '{s+=$1} END {printf "%d files, %.1f GB to download\n", NR, s/1073741824}'

Finder offers the same job as a menu item: select the folder, right-click, Download Now. I did not drive that menu, so take it as the obvious GUI route rather than a measured one — but it is asking for something the framework genuinely models, not a loop Finder runs itself. fileproviderctl evaluate on a folder reports isRecursivelyDownloaded as a flag distinct from isDownloaded, and on a folder whose contents were partly evicted the two disagreed: the folder itself downloaded, its subtree not.

Why the folder copy fails when a single file is fine

Two different things can happen when a copy runs into files that are not really there, and it is worth knowing which one you are looking at. Finder can stop and ask whether to skip the ones it cannot fetch. Or it can stop dead, with the message at the top of this page, and copy nothing at all.

Finder has two behaviours here and it is worth telling them apart, because both are in its string table:

PE120 = "The file “^0” cannot be downloaded. Do you want to skip it?"
PE121 = "The folder “^0” contains items which cannot be downloaded. Do you want to skip these items?"

That is the soft path: Finder asks, you skip, and the copy finishes with holes in it that you will not notice until you need one of the missing files. CS201 and CS202 are the hard stop — no offer to skip, nothing copied.

Which one you get depends on what refused, and here is the honest boundary of this page. If this error is on your screen, something between your Mac and the provider is declining the download — that is the diagnosis, not a verdict on your Mac. On a machine that can reach iCloud I could not reproduce CS201 at all: every route that actually reads an evicted file — cat, cp, mv out of iCloud Drive — downloaded on demand and succeeded. I did not take the machine offline to force the failure, so what follows is read off the error’s own wording rather than off a reproduction.

The message does not mean “placeholders cannot be copied”. It means the download did not happen. Work down the family table at the top — offline, signed out, provider extension not running, cloud quota full — fix that, and then force the download before the copy rather than during it.

The other reliable trigger is an application that will not wait. Backup and sync tools read files directly, and one that treats a stalled read as a failure will report exactly this error on a folder that Finder, doing the same work behind a progress bar, copies without complaint.

Dropbox, Google Drive, OneDrive and the rest

None of this is an iCloud-only story. Dropbox, Google Drive and OneDrive keep their online-only files the same way and hand them to macOS through the same plumbing, so you get the same dialogs and the same right-click Download Now on them.

Third-party clouds mount through the same File Provider framework Apple uses for iCloud Drive, and they appear as folders in ~/Library/CloudStorage. Their online-only files use the same machinery. The eight messages above are worded for that generality rather than for iCloud specifically — Extension internal error is about a provider extension, and CS207 and CS208 exist precisely so Finder can name which provider failed — so expect the same dialogs over a Dropbox or Google Drive file. I could not confirm the dataless flag on one from the terminal, for the reason immediately below.

Want to see what is really mounted? fileproviderctl dump | grep "containing bundle identifier" prints just the providers actually registered on your Mac — keep the grep, because the full dump takes a minute and pours out pages of the daemon’s own diagnostics, which read far more broken than anything on your Mac actually is. The short list is worth a look for two reasons that are not obvious. Apple’s own components are in that list alongside the ones you installed — Photos registers a provider too — so the count is never just “my clouds”. And the list does not match the folders in CloudStorage: on my Mac a Google Drive folder from 2023 is still sitting there with no registered provider behind it. A folder in CloudStorage is not proof that anything is still mounted.

One trap will cost you an afternoon if nobody warns you:

$ ls ~/Library/CloudStorage/Dropbox
ls: /Users/me/Library/CloudStorage/Dropbox: Operation not permitted

That is macOS privacy protection rather than a permissions problem — the folder is owned by you, and listing its parent works fine. It is also not uniform: on the same Mac, in the same shell, Dropbox and the Google Drive folder both refused while ProtonDrive-… listed normally, so do not conclude anything from one provider working. Where you do hit it, Full Disk Access for your terminal — System Settings ▸ Privacy & Security ▸ Full Disk Access — is the remedy to try; I did not grant it, so I am pointing at the door rather than reporting what is behind it. ~/Library/Mobile Documents, where iCloud Drive lives, is not restricted this way, which is why every command above works there unmodified.

Finder is not subject to that restriction either, so Download Now is the path of least resistance for third-party clouds even if you would rather use the terminal for iCloud.

Keeping it from happening again

Two levers, and both cost the same thing — disk space.

Turning Optimize Mac Storage off stops new evictions. It is the blunt version, and it needs your whole iCloud Drive to fit locally. The surgical version is Finder’s Keep Downloaded on the specific folders you back up or sync elsewhere: those stay materialised, the rest of the drive is still allowed to float. In an item’s File Provider state that shows up as isKeepDownloaded, sitting next to isDownloaded, so it is a real per-item property rather than a Finder-only decoration.

What FileBo does about cloud files, and what it does not

This is our own site, so here is the honest accounting — and it is a smaller note than you might expect.

FileBo is a panel of your recent files, and your cloud folders are part of what it watches, so files that live in the cloud turn up in the list alongside everything else. Open one from there and it opens; if the contents were not on the Mac, they come down on the way. That last part is not FileBo being clever — it is what macOS does for anything that reads a file, Finder included.

If you do want the mechanical version: it watches ~/Library/CloudStorage and iCloud Drive among its ten default folders, so cloud files do show up in it. Its one piece of placeholder handling is aimed squarely at the legacy shape: a hidden .Report.pdf.icloud stub is kept in the list instead of being dropped with the other dot-files, shown under the real name with a download badge, announced to VoiceOver as “in iCloud, not downloaded”, and double-clicked it asks iCloud to start the download rather than opening the stub. Which means that on the macOS this page is about, where eviction leaves a dataless file under its own name and no stub at all, none of that fires — an evicted file is simply an ordinary tile, and opening it downloads it because macOS does that for any reader.

And the limit: there is no batch download, so folder-sized jobs — the backup, the migration, the project coming off the machine — belong to the recipes above. For the single file that refuses to open, though — the CS202 with no name attached, the attachment that will not preview — a panel where that file is already sitting one keystroke away is exactly the right size of tool.

A different mystery that arrives in the same week

This one catches people alongside the error above: a file you have never opened has no kMDItemLastUsedDate at all. mdls on my test file omitted the attribute entirely, and mdls -name kMDItemLastUsedDate returned (null). That matters because Finder’s Recents is a saved Spotlight query whose first condition is kMDItemLastUsedDate = "*" — so a file that has never been opened cannot appear there until something opens it, placeholder or not. Different mechanism, different fix, and it has its own page.