A file that will not open because iCloud kept a placeholder

The file is right there in the Finder with its name, its date and a sensible size, and double-clicking it produces an error saying it could not be opened, or a progress ring that never fills. Nothing is corrupted. The item you are looking at is a placeholder, and the actual contents live on Apple’s servers.

macOS does this on purpose to save space, and it is usually invisible. It becomes very visible when you are offline, when the account is full, or when the download quietly fails.

How to recognize a placeholder

Look at the file in a Finder window with the column for iCloud status visible, or just look at the icon.

A cloud icon with a downward arrow beside the name means the file is in iCloud and not on this Mac. A partly filled circle means a download is in progress. No icon means the file is local and this is not your problem.

A second check that works everywhere: select the file, press Command-I for Get Info, and compare Size with the value in parentheses after it. A placeholder reports the logical size of the document while occupying almost nothing on disk. If Get Info shows a two-gigabyte video but the folder it lives in has barely grown, you are looking at a stub.

This applies to files in iCloud Drive, in Desktop and Documents when those folders are synced, and to originals in a Photos library set to optimize storage.

Why the Mac removed the contents

Two settings produce placeholders.

Optimize Mac Storage. In System Settings, under your name, then iCloud, iCloud Drive has an Optimize Mac Storage option. When the startup disk gets tight, macOS evicts the contents of files you have not opened recently and keeps the names. It does not ask first, and it does not tell you afterwards.

Manual eviction. Right-clicking a file and choosing Remove Download does the same thing deliberately.

Either way the file is still yours and still complete in iCloud. The Mac is simply not holding a copy.

Getting the real file back

Start with the direct route.

1. Right-click the file in the Finder and choose Download Now if it appears.
2. If it does not, double-click the file and wait. Opening a placeholder triggers a download.
3. Watch the progress ring on the icon. A ring that fills and disappears means you now have the real file.

If the ring stalls, work through the usual blockers in order.

Check that you are actually online and signed in: System Settings, your name, and confirm iCloud is not showing a sign-in prompt. Check that iCloud storage is not full, since a full account can stall sync in both directions. Check that the startup disk has room, because macOS will not download a large file into a nearly full volume and the failure is often silent. Your Mac says the disk is full when Finder says it is not covers the version of this where the space looks available and is not.

A stalled sync can often be nudged by quitting and reopening the Finder window, or by logging out and back in. Restarting the Mac is a blunt instrument that works more often than it should.

When the download finishes and the file is still wrong

This is where a placeholder problem turns into a file problem, and the distinction matters.

If the download completes but the file opens to an error, a black screen, or a fraction of its pages, what you have is a transfer that ended early or a copy that was already damaged before it went up. The cloud icon is gone, Get Info shows real bytes on disk, and the file still will not work.

Check the size against what you expect. A video that should be four gigabytes and arrived as four hundred megabytes did not finish, whatever the Finder says. Verifying a file arrived intact shows how to confirm that properly rather than trusting appearances.

For a file that genuinely arrived short, the first move is to delete the local copy (Remove Download, not Move to Trash, so the cloud copy is untouched) and download again. A second attempt over a stable connection fixes most of these.

If a second download produces the same broken file, the copy in iCloud is itself damaged, and re-downloading forever will not change that. At that point you are repairing content rather than fixing sync.

Repairing what actually came down

A truncated video, a PDF missing its cross-reference table, or a DOCX whose archive directory did not arrive can often be partly rebuilt from the bytes you do have.

Manatee does this on the Mac in Repair mode: drop the file on the menu bar icon and it scans for usable content, rebuilds the index or table where it can, and writes a new file alongside. It never modifies the file you gave it, which matters when the copy in hand is the only one. The result is reported as Fixed, Partial or Not fixable, with Partial meaning something specific such as the first eleven minutes of a video or thirty-four of forty-one pages.

Two limits, stated plainly. Manatee works entirely on your Mac with the file in front of it, so it cannot fetch the missing part from iCloud. And it is not an undelete or recovery tool: if the contents were never downloaded, there is nothing local to repair, and the answer is to fix the download rather than to run a repair pass. Why files get corrupted and what can actually be recovered draws that line more fully.

Working offline without surprises

If you know you will be without a connection, make the files local first.

Select the folder you need, right-click, and choose Download Now. Do it the evening before rather than at the gate, because a large folder takes real time. Then confirm with Get Info that the size on disk matches the logical size.

For anything you cannot afford to lose access to, turning off Optimize Mac Storage is the honest fix, at the cost of disk space. A project folder kept outside iCloud entirely, with its own backup, is better still for work in progress.

Questions

Does removing a download delete the file? No. Remove Download clears the local contents and leaves the file in iCloud. Move to Trash deletes it everywhere.

Why does the file show a size if it is not really here? The Finder reports what the document contains, not what is on this disk. The value in parentheses in Get Info is the one that reflects local storage.

Can I stop macOS from evicting files on its own? Turn off Optimize Mac Storage in iCloud Drive settings. The Mac will then keep every synced file local, which needs enough free space to hold all of it.

A downloaded file opens but half the pages are blank. Placeholder problem? No. Once the contents are local, blank pages point at the document itself, which is covered in a PDF that opens with blank pages in Preview.